pupnp (libupnp) snapshot from SourceForge: git clone git://pupnp.git.sourceforge...
[igd2-for-linux:pandonghui1211s-igd2-for-linux.git] / pupnp_branch-1.6.x / threadutil / inc / TimerThread.h
1 /*******************************************************************************
2  *
3  * Copyright (c) 2000-2003 Intel Corporation 
4  * All rights reserved. 
5  *
6  * Redistribution and use in source and binary forms, with or without 
7  * modification, are permitted provided that the following conditions are met: 
8  *
9  * * Redistributions of source code must retain the above copyright notice, 
10  * this list of conditions and the following disclaimer. 
11  * * Redistributions in binary form must reproduce the above copyright notice, 
12  * this list of conditions and the following disclaimer in the documentation 
13  * and/or other materials provided with the distribution. 
14  * * Neither name of Intel Corporation nor the names of its contributors 
15  * may be used to endorse or promote products derived from this software 
16  * without specific prior written permission.
17  * 
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
22  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
25  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
26  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
27  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  *
30  ******************************************************************************/
31
32 #ifndef TIMERTHREAD_H
33 #define TIMERTHREAD_H
34
35 #include "ithread.h"
36 #include "LinkedList.h"
37 #include "FreeList.h"
38 #include "ThreadPool.h"
39
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43
44 #define INVALID_EVENT_ID (-10 & 1<<29)
45
46 /* Timeout Types */
47 /* absolute means in seconds from Jan 1, 1970 */
48 /* relative means in seconds from current time */
49 typedef enum timeoutType {ABS_SEC,REL_SEC} TimeoutType;
50
51
52 /****************************************************************************
53  * Name: TimerThread
54  * 
55  *   Description:
56  *     A timer thread similar to the one in the Upnp SDK that allows
57  *     the scheduling of a job to run at a specified time in the future
58  *     Because the timer thread uses the thread pool there is no 
59  *     gurantee of timing, only approximate timing.
60  *     Uses ThreadPool, Mutex, Condition, Thread
61  *    
62  * 
63  *****************************************************************************/
64 typedef struct TIMERTHREAD
65 {
66   ithread_mutex_t mutex;
67   ithread_cond_t condition;
68   int lastEventId;
69   LinkedList eventQ;
70   int shutdown;
71   FreeList freeEvents;
72   ThreadPool *tp;
73 } TimerThread;
74
75
76 /****************************************************************************
77  * Name: TimerEvent
78  * 
79  *   Description:
80  *     
81  *     Struct to contain information for a timer event.
82  *     Internal to the TimerThread
83  *   
84  *****************************************************************************/
85 typedef struct TIMEREVENT
86 {
87   ThreadPoolJob job;
88   time_t eventTime; /* absolute time for event in seconds since Jan 1, 1970 */
89   Duration persistent;  /* long term or short term job */
90   int id;
91 } TimerEvent;
92
93
94
95
96 /************************************************************************
97  * Function: TimerThreadInit
98  * 
99  *  Description:
100  *     Initializes and starts timer thread.
101  *
102  *  Parameters:
103  *             timer - valid timer thread pointer.
104  *             tp  - valid thread pool to use. Must be
105  *                   started. Must be valid for lifetime
106  *                   of timer.  Timer must be shutdown
107  *                   BEFORE thread pool.
108  *  Return:
109  *            0 on success, nonzero on failure
110  *            Returns error from ThreadPoolAddPersistent on failure.
111  *
112  ************************************************************************/
113 int TimerThreadInit(TimerThread *timer,
114                     ThreadPool *tp);
115
116
117 /************************************************************************
118  * Function: TimerThreadSchedule
119  * 
120  *  Description:
121  *     Schedules an event to run at a specified time.
122  *
123  *  Parameters:
124  *             timer - valid timer thread pointer.
125  *             time_t - time of event.
126  *                      either in absolute seconds,
127  *                      or relative seconds in the future.
128  *             timeoutType - either ABS_SEC, or REL_SEC.
129  *                           if REL_SEC, then the event
130  *                           will be scheduled at the
131  *                           current time + REL_SEC.
132  *             job-> valid Thread pool job with following fields
133  *             func - function to schedule
134  *             arg - argument to function
135  *             priority - priority of job.
136  *         
137  *             id - id of timer event. (out, can be null)
138  *  Return:
139  *            0 on success, nonzero on failure
140  *            EOUTOFMEM if not enough memory to schedule job.
141  *
142  ************************************************************************/
143 int TimerThreadSchedule(TimerThread* timer,
144                         time_t time, 
145                         TimeoutType type,
146                         ThreadPoolJob *job,
147                         Duration duration,
148                         int *id);
149
150 /************************************************************************
151  * Function: TimerThreadRemove
152  * 
153  *  Description:
154  *     Removes an event from the timer Q.
155  *     Events can only be removed 
156  *     before they have been placed in the
157  *     thread pool.
158  *
159  *  Parameters:
160  *             timer - valid timer thread pointer.
161  *             id - id of event to remove.
162  *             ThreadPoolJob *out - space for thread pool job.
163  *  Return:
164  *            0 on success, 
165  *            INVALID_EVENT_ID on failure
166  *                       
167  ************************************************************************/
168 int TimerThreadRemove(TimerThread *timer,
169                            int id,
170                            ThreadPoolJob *out);
171
172 /************************************************************************
173  * Function: TimerThreadShutdown
174  * 
175  *  Description:
176  *    Shutdown the timer thread
177  *    Events scheduled in the future will NOT be run.
178  *    Timer thread should be shutdown BEFORE it's associated
179  *    thread pool.
180  *  Returns:
181  *    returns 0 if succesfull,
182  *            nonzero otherwise.
183  *            Always returns 0.
184  ***********************************************************************/   
185 int TimerThreadShutdown(TimerThread *timer);
186
187 #ifdef __cplusplus
188 }
189 #endif
190
191 #endif /* TIMER_THREAD_H */
192