Kannel: Open Source WAP and SMS gateway  svn-r5335
gwthread.h
Go to the documentation of this file.
1 /* ====================================================================
2  * The Kannel Software License, Version 1.0
3  *
4  * Copyright (c) 2001-2018 Kannel Group
5  * Copyright (c) 1998-2001 WapIT Ltd.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Kannel Group (http://www.kannel.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Kannel" and "Kannel Group" must not be used to
28  * endorse or promote products derived from this software without
29  * prior written permission. For written permission, please
30  * contact org@kannel.org.
31  *
32  * 5. Products derived from this software may not be called "Kannel",
33  * nor may "Kannel" appear in their name, without prior written
34  * permission of the Kannel Group.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE KANNEL GROUP OR ITS CONTRIBUTORS
40  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
41  * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
42  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
43  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
44  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
45  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
46  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
47  * ====================================================================
48  *
49  * This software consists of voluntary contributions made by many
50  * individuals on behalf of the Kannel Group. For more information on
51  * the Kannel Group, please see <http://www.kannel.org/>.
52  *
53  * Portions of this software are based upon software originally written at
54  * WapIT Ltd., Helsinki, Finland for the Kannel project.
55  */
56 
57 /*
58  * gwthread.h - threads wrapper with interruptible sleep and poll operations.
59  *
60  * This is a (partial) encapsulation of threads. It provides functions
61  * to create new threads and to manipulate threads. It will eventually
62  * be extended to encapsulate all pthread functions we use, so that
63  * non-POSIX platforms can plug in their own versions.
64  *
65  * Richard Braakman
66  */
67 
68 #ifndef GWTHREAD_H
69 #define GWTHREAD_H
70 
71 #include "gw-config.h"
72 #ifdef HAVE_SYS_POLL_H
73 #include <sys/poll.h>
74 #endif
75 
76 /* gwthread_self() must return this value for the main thread. */
77 #define MAIN_THREAD_ID 0
78 
79 typedef void gwthread_func_t(void *arg);
80 
81 /* Called by the gwlib init code */
82 void gwthread_init(void);
83 void gwthread_shutdown(void);
84 
85 /* Start a new thread, running func(arg). Return the new thread ID
86  * on success, or -1 on failure. Thread IDs are unique during the lifetime
87  * of the entire process, unless you use more than LONG_MAX threads. */
88 long gwthread_create_real(gwthread_func_t *func, const char *funcname,
89  void *arg);
90 #define gwthread_create(func, arg) \
91  (gwthread_create_real(func, __FILE__ ":" #func, arg))
92 
93 /* Wait for the other thread to terminate. Return immediately if it
94  * has already terminated. */
95 void gwthread_join(long thread);
96 
97 /* Wait for all threads whose main function is `func' to terminate.
98  * Return immediately if none are running. */
100 
101 /* Wait for all threads to terminate. Return immediately if none
102  * are running. This function is not intended to be called if new
103  * threads are still being created, and it may not notice such threads. */
104 void gwthread_join_all(void);
105 
106 /* Return the thread id of this thread. Note that it may be called for
107  * the main thread even before the gwthread library has been initialized
108  * and after it had been shut down. */
109 long gwthread_self(void);
110 
111 /* Same as above, but returns the process id (pid) of the thread. */
112 long gwthread_self_pid(void);
113 
114 /* Same as gwthread_self() and gwthread_self_pid() combined to one void
115  * call. Returns the internal thread id and the process id. */
116 void gwthread_self_ids(long *tid, long *pid);
117 
118 /* If the other thread is currently in gwthread_pollfd or gwthread_sleep,
119  * make it return immediately. Otherwise, make it return immediately, the
120  * next time it calls one of those functions. */
121 void gwthread_wakeup(long thread);
122 
123 /* Wake up all threads */
124 void gwthread_wakeup_all(void);
125 
126 /* Wrapper around the poll() system call, for one file descriptor.
127  * "events" is a set of the flags defined in <sys/poll.h>, usually
128  * POLLIN, POLLOUT, or (POLLIN|POLLOUT). Return when one of the
129  * events is true, or when another thread calls gwthread_wakeup on us, or
130  * when the timeout expires. The timeout is specified in seconds,
131  * and a negative value means do not time out. Return the revents
132  * structure filled in by poll() for this fd. Return -1 if something
133  * went wrong. */
134 int gwthread_pollfd(int fd, int events, double timeout);
135 
136 /* Wrapper around the poll() system call, for an array of file
137  * descriptors. The difference with normal poll is that the
138  * thread can be woken up with gwthread_wakeup. timeout is in seconds. */
139 /* NOTE: This interface will probably change in the future, because currently
140  * it is hard to implement efficiently. */
141 int gwthread_poll(struct pollfd *fds, long numfds, double timeout);
142 
143 /* Sleep until "seconds" seconds have elapsed, or until another thread
144  * calls gwthread_wakeup on us. Fractional seconds are allowed. */
145 void gwthread_sleep(double seconds);
146 
147 /* Sleep until "seconds" seconds have elapsed, or until another thread
148  * calls gwthread_wakeup on us. Fractional seconds are allowed. */
149 void gwthread_sleep_micro(double dseconds);
150 
151 /* Force a specific thread to terminate. Returns 0 on success, -1 if the
152  * thread has been terminated while calling and non-zero for the pthread
153  * specific error code.
154  */
155 int gwthread_cancel(long thread);
156 
157 /*
158  * Check wheather this thread should handle the given signal.
159  * Since signals are thread specific, this needs to be handled
160  * by the thread code here. This is mostly to cope with
161  * "interesting" implementations of "pthreads"
162  */
163 int gwthread_shouldhandlesignal(int signal);
164 
165 /* Dump the current signal mask for this thread. This will print out a
166  * set of debug messages that state the signal handling status for the
167  * first 32 signals on the current system. Return -1 if something goes
168  * wrong.
169  *
170  * Debugging purposes mostly so it can be ignored on platforms
171  * where this isn't applicable.
172  */
173 int gwthread_dumpsigmask(void);
174 
175 
176 #endif
void gwthread_self_ids(long *tid, long *pid)
void gwthread_join_all(void)
long gwthread_self_pid(void)
void gwthread_join_every(gwthread_func_t *func)
void gwthread_sleep_micro(double dseconds)
void gwthread_wakeup(long thread)
void gwthread_sleep(double seconds)
int gwthread_poll(struct pollfd *fds, long numfds, double timeout)
gwthread_func_t * func
void gwthread_func_t(void *arg)
Definition: gwthread.h:79
long gwthread_create_real(gwthread_func_t *func, const char *funcname, void *arg)
int gwthread_pollfd(int fd, int events, double timeout)
Definition: gwpoll.h:84
int gwthread_shouldhandlesignal(int signal)
int gwthread_cancel(long thread)
void gwthread_shutdown(void)
void gwthread_init(void)
void gwthread_wakeup_all(void)
int gwthread_dumpsigmask(void)
void gwthread_join(long thread)
long gwthread_self(void)
See file LICENSE for details about the license agreement for using, modifying, copying or deriving work from this software.