timed thread stuff
[monky] / src / timed_thread.c
1 /* $Id$ */
2
3 /* 
4  * timed_thread.c: Abstraction layer for timed threads
5  *
6  * Copyright (C) 2006-2007 Philip Kovacs pkovacs@users.sourceforge.net
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public
10  * License as published by the Free Software Foundation; either
11  * version 2.1 of the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with this library; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
21  * USA.
22  *
23  */
24
25 #include <pthread.h>
26 #include <assert.h>
27 #include <errno.h>
28 #include <stdlib.h>
29 #include <stdio.h>
30 #include <time.h>
31 #ifndef HAVE_CLOCK_GETTIME
32 #include <sys/time.h>
33 #endif
34 #include "timed_thread.h"
35
36 /* Abstraction layer for timed threads */
37
38 static int now (struct timespec *);
39
40 /* private */
41 struct _timed_thread 
42 {
43   pthread_t thread;               /* thread itself */
44   pthread_attr_t thread_attr;     /* thread attributes */
45   pthread_mutex_t cs_mutex;       /* critical section mutex */
46   pthread_mutex_t runnable_mutex; /* only for the runnable_cond */
47   pthread_cond_t runnable_cond;   /* signalled to stop the thread */
48   void *(*start_routine)(void*);  /* thread function to run */
49   void *arg;                      /* thread function argument */
50   struct timespec interval_time;  /* interval_usecs as a struct timespec */
51 };
52
53 /* linked list of created threads */
54 typedef struct _timed_thread_list
55 {
56   timed_thread *p_timed_thread;
57   timed_thread **addr_of_p_timed_thread;
58   struct _timed_thread_list *next;
59 } timed_thread_node, timed_thread_list;
60
61 static timed_thread_list *p_timed_thread_list_head = NULL;
62 static timed_thread_list *p_timed_thread_list_tail = NULL;
63
64 static int now (struct timespec *abstime)
65 {
66   if (!abstime)
67     return (-1);
68
69 #ifdef HAVE_CLOCK_GETTIME
70   return clock_gettime (CLOCK_REALTIME, &abstime);
71 #else
72   /* fallback to gettimeofday () */
73   struct timeval tv;
74   if (gettimeofday (&tv, NULL) != 0)
75     return (-1);
76
77   abstime->tv_sec = tv.tv_sec;
78   abstime->tv_nsec = tv.tv_usec * 1000;
79   return 0;
80 #endif
81 }
82
83
84 /* create a timed thread (object creation only) */
85 timed_thread* 
86 timed_thread_create (void *(*start_routine)(void*), void *arg, unsigned int interval_usecs)
87 {
88   timed_thread *p_timed_thread;
89
90   assert ((start_routine != NULL) && (interval_usecs >= MINIMUM_INTERVAL_USECS));
91
92   if ((p_timed_thread = calloc (sizeof(timed_thread), 1)) == 0)
93     return NULL;
94
95   /* init attributes, e.g. joinable thread */
96   pthread_attr_init (&p_timed_thread->thread_attr);
97   pthread_attr_setdetachstate (&p_timed_thread->thread_attr, PTHREAD_CREATE_JOINABLE);
98   /* init mutexes */
99   pthread_mutex_init (&p_timed_thread->cs_mutex, NULL);
100   pthread_mutex_init (&p_timed_thread->runnable_mutex, NULL);
101   /* init cond */
102   pthread_cond_init (&p_timed_thread->runnable_cond, NULL);
103
104   p_timed_thread->start_routine = start_routine;
105   p_timed_thread->arg = arg;
106
107   /* seconds portion of the microseconds interval */
108   p_timed_thread->interval_time.tv_sec = (time_t)(interval_usecs / 1000000);
109   /* remaining microseconds convert to nanoseconds */
110   p_timed_thread->interval_time.tv_nsec = (long)((interval_usecs % 1000000) * 1000);
111
112   return p_timed_thread;
113 }
114
115 /* run a timed thread (drop the thread and run it) */
116 int 
117 timed_thread_run (timed_thread* p_timed_thread)
118 {
119   return pthread_create (&p_timed_thread->thread, &p_timed_thread->thread_attr,
120                          p_timed_thread->start_routine, p_timed_thread->arg);
121 }
122
123 /* destroy a timed thread.
124  * optional addr_of_p_timed_thread to set callers pointer to NULL as a convenience. */
125 void 
126 timed_thread_destroy (timed_thread* p_timed_thread, timed_thread** addr_of_p_timed_thread)
127 {
128   assert (p_timed_thread != NULL);
129   assert ((addr_of_p_timed_thread == NULL) || (*addr_of_p_timed_thread == p_timed_thread));
130
131   /* signal thread to stop */
132   pthread_mutex_lock (&p_timed_thread->runnable_mutex);
133   pthread_cond_signal (&p_timed_thread->runnable_cond);
134   pthread_mutex_unlock (&p_timed_thread->runnable_mutex);
135
136   /* join the terminating thread */
137   pthread_join (p_timed_thread->thread, NULL);
138
139   /* clean up */
140   pthread_attr_destroy (&p_timed_thread->thread_attr);
141   pthread_mutex_destroy (&p_timed_thread->cs_mutex);
142   pthread_mutex_destroy (&p_timed_thread->runnable_mutex);
143   pthread_cond_destroy (&p_timed_thread->runnable_cond);
144
145   free (p_timed_thread);
146   if (addr_of_p_timed_thread)
147     *addr_of_p_timed_thread = NULL;
148 }
149
150
151 /* lock a timed thread for critical section activity */
152 int
153 timed_thread_lock (timed_thread* p_timed_thread)
154 {
155   assert (p_timed_thread != NULL);
156
157   return pthread_mutex_lock (&p_timed_thread->cs_mutex);
158 }
159
160
161 /* unlock a timed thread after critical section activity */
162 int
163 timed_thread_unlock (timed_thread* p_timed_thread)
164 {
165   assert (p_timed_thread != NULL);
166
167   return pthread_mutex_unlock (&p_timed_thread->cs_mutex);
168 }
169
170
171 /* thread waits interval_usecs for runnable_cond to be signaled.  returns 1 if signaled, 
172  * -1 on error, and 0 otherwise.  caller should call timed_thread_exit() on any non-zero 
173  * return value. */
174 int 
175 timed_thread_test (timed_thread* p_timed_thread)
176 {
177   struct timespec wait_time;
178   int rc;
179
180   assert (p_timed_thread != NULL);
181
182   if (now (&wait_time)) return (-1);
183   /* move the clock backward 1 sec to shift sync slightly earlier than UI thread */
184   wait_time.tv_sec -= 1;
185   /* now add in the wait interval */
186   wait_time.tv_sec += p_timed_thread->interval_time.tv_sec;
187   wait_time.tv_nsec += p_timed_thread->interval_time.tv_nsec;
188
189   /* acquire runnable_cond mutex */
190   if (pthread_mutex_lock (&p_timed_thread->runnable_mutex))
191     return (-1);  /* could not acquire runnable_cond mutex, so tell caller to exit thread */
192
193   /* release mutex and wait until future time for runnable_cond to signal */
194   rc = pthread_cond_timedwait (&p_timed_thread->runnable_cond,
195                                &p_timed_thread->runnable_mutex,
196                                &wait_time);
197   /* mutex re-acquired, so release it */
198   pthread_mutex_unlock (&p_timed_thread->runnable_mutex);
199
200   if (rc==0)
201     return 1; /* runnable_cond was signaled, so tell caller to exit thread */
202
203   /* tell caller not to exit yet */
204   return 0;
205 }
206
207
208 /* exit a timed thread */
209 void 
210 timed_thread_exit (timed_thread* p_timed_thread)
211 {
212   assert (p_timed_thread != NULL);
213
214   pthread_exit (NULL);
215 }
216
217
218 /* register a timed thread for future destruction via timed_thread_destroy_registered_threads() */
219 int 
220 timed_thread_register (timed_thread* p_timed_thread, timed_thread** addr_of_p_timed_thread)
221 {
222   timed_thread_node *p_node;
223
224   assert ((addr_of_p_timed_thread == NULL) || (*addr_of_p_timed_thread == p_timed_thread));
225
226   if ((p_node = calloc (sizeof (timed_thread_node), 1)) == 0)
227     return 0;
228     
229   p_node->p_timed_thread = p_timed_thread;
230   p_node->addr_of_p_timed_thread = addr_of_p_timed_thread;
231   p_node->next = NULL;
232
233   if (!p_timed_thread_list_tail)
234   {
235     /* first node of empty list */
236     p_timed_thread_list_tail = p_node;
237     p_timed_thread_list_head = p_node;
238   }
239   else
240   {
241     /* add node to tail of non-empty list */
242     p_timed_thread_list_tail->next = p_node;
243     p_timed_thread_list_tail = p_node;
244   }
245
246   return 0;
247 }
248
249
250 /* destroy all registered timed threads */
251 void 
252 timed_thread_destroy_registered_threads (void)
253 {
254   timed_thread_node *p_node, *p_next;
255
256   for (p_node=p_timed_thread_list_head;
257        p_node;
258        p_node=p_next)
259   {
260     p_next = p_node->next;
261     timed_thread_destroy (p_node->p_timed_thread, p_node->addr_of_p_timed_thread);
262     free (p_node);
263     p_node = NULL;
264   }
265
266   p_timed_thread_list_head = NULL;
267   p_timed_thread_list_tail = NULL;
268 }
269