1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - CARD - libraries
3   File:     card_task.h
4 
5   Copyright 2007-2008 Nintendo. All rights reserved.
6 
7   These coded instructions, statements, and computer programs contain
8   proprietary information of Nintendo of America Inc. and/or Nintendo
9   Company Ltd., and are protected by Federal copyright law. They may
10   not be disclosed to third parties or copied or duplicated in any form,
11   in whole or in part, without the prior written consent of Nintendo.
12 
13   $Date:: 2008-09-17#$
14   $Rev: 8556 $
15   $Author: okubata_ryoma $
16 
17  *---------------------------------------------------------------------------*/
18 #ifndef NITRO_LIBRARIES_CARD_TASK_H__
19 #define NITRO_LIBRARIES_CARD_TASK_H__
20 
21 
22 #include <nitro/os.h>
23 
24 
25 /*---------------------------------------------------------------------------*
26  * This utility manages a priority task queue.
27  * This is used only within the CARD library, but it could be taken and used separately.
28  *---------------------------------------------------------------------------*/
29 
30 
31 #ifdef __cplusplus
32 extern  "C"
33 {
34 #endif
35 
36 
37 /*---------------------------------------------------------------------------*/
38 /* Declarations */
39 
40 
41 // Task structure that causes a worker thread to run a process in the background.
42 struct CARDTask;
43 typedef void (*CARDTaskFunction)(struct CARDTask *);
44 
45 typedef struct CARDTask
46 {
47     struct CARDTask    *next;
48     u32                 priority;
49     void               *userdata;
50     CARDTaskFunction    function;
51     CARDTaskFunction    callback;
52 }
53 CARDTask;
54 
55 // Task queue structure.
56 typedef struct CARDTaskQueue
57 {
58     CARDTask * volatile list;
59     OSThreadQueue       workers[1];
60     u32                 quit:1;
61     u32                 dummy:31;
62 }
63 CARDTaskQueue;
64 
65 
66 /*---------------------------------------------------------------------------*/
67 /* functions */
68 
69 /*---------------------------------------------------------------------------*
70   Name:         CARDi_InitTaskQueue
71 
72   Description:  Initializes a task queue structure.
73 
74   Arguments:    queue:    CARDTaskQueue structure.
75 
76   Returns:      None.
77  *---------------------------------------------------------------------------*/
78 void CARDi_InitTaskQueue(CARDTaskQueue *queue);
79 
80 /*---------------------------------------------------------------------------*
81   Name:         CARDi_QuitTaskQueue
82 
83   Description:  Stops all worker threads that observe the task queue and sets their states to QUIT.
84                 The task queue's state is left unchanged, and tasks in progress will continue to completion.
85 
86   Arguments:    queue    CARDTaskQueue structure.
87 
88   Returns:      None.
89  *---------------------------------------------------------------------------*/
90 void CARDi_QuitTaskQueue(CARDTaskQueue *queue);
91 
92 /*---------------------------------------------------------------------------*
93   Name:         CARDi_InitTask
94 
95   Description:  Initializes a task structure.
96 
97   Arguments:    task:      CARDTask structure.
98                 priority:  Thread priority.
99                 userdata:  Arbitrary user-defined data to associate with a task.
100                 function:  Function pointer to the task to run.
101                 callback:  Callback to invoke after task completion. (NULL if this is not necessary)
102 
103   Returns:      None.
104  *---------------------------------------------------------------------------*/
105 void CARDi_InitTask(CARDTask *task, u32 priority, void *userdata,
106                     CARDTaskFunction function, CARDTaskFunction callback);
107 
108 /*---------------------------------------------------------------------------*
109   Name:         CARDi_ProcessTask
110 
111   Description:  Runs a task or adds it to a task queue.
112 
113   Arguments:    queue:    CARDTaskQueue structure.
114                 task:     Task to run or add to the queue.
115                 blocking:        TRUE to run it now without adding it to the queue.
116                                  FALSE to add it to the queue and let a worker thread process it.
117                 changePriority:  TRUE to run at the priority set for the task.
118 
119   Returns:      None.
120  *---------------------------------------------------------------------------*/
121 void CARDi_ProcessTask(CARDTaskQueue *queue, CARDTask *task, BOOL blocking, BOOL changePriority);
122 
123 /*---------------------------------------------------------------------------*
124   Name:         CARDi_ReceiveTask
125 
126   Description:  Gets the next task from a task queue.
127 
128   Arguments:    queue:    CARDTaskQueue structure.
129                 blocking:  TRUE to block on an empty queue.
130 
131   Returns:      The new available task.
132                 NULL during non-blocking mode if the queue is empty, or whenever the queue's state is QUIT.
133  *---------------------------------------------------------------------------*/
134 CARDTask* CARDi_ReceiveTask(CARDTaskQueue *queue, BOOL blocking);
135 
136 /*---------------------------------------------------------------------------*
137   Name:         CARDi_TaskWorkerProcedure
138 
139   Description:  Worker thread procedure that continues to monitor a task thread.
140                 The thread created by specifying this procedure will continue to process the task until the CARDi_QuitTask function is issued.
141 
142                 You may create multiple worker threads for a single task queue.
143 
144   Arguments:    arg:  The CARDTaskQueue structure that should be monitored.
145 
146   Returns:      None.
147  *---------------------------------------------------------------------------*/
148 void CARDi_TaskWorkerProcedure(void *arg);
149 
150 
151 /*---------------------------------------------------------------------------*/
152 
153 #ifdef __cplusplus
154 } // extern "C"
155 #endif
156 
157 
158 #endif // NITRO_LIBRARIES_CARD_TASK_H__
159