1 /* Pseudothread handler.
3 * This library is free software; you can redistribute it and/or
4 * modify it under the terms of the GNU Library General Public
5 * License as published by the Free Software Foundation; either
6 * version 2 of the License, or (at your option) any later version.
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 * Library General Public License for more details.
13 * You should have received a copy of the GNU Library General Public
14 * License along with this library; if not, write to the Free
15 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17 * $Id: pthr_pseudothread.h,v 1.13 2002/12/01 14:29:30 rich Exp $
20 #ifndef PTHR_PSEUDOTHREAD_H
21 #define PTHR_PSEUDOTHREAD_H
25 #include <sys/types.h>
27 #include <sys/socket.h>
34 #include "pthr_reactor.h"
35 #include "pthr_context.h"
38 typedef struct pseudothread *pseudothread;
40 /* Function: current_pth - current pseudothread
42 * @code{current_pth} is a global variable containing the currently
45 extern pseudothread current_pth;
47 /* Function: pseudothread_set_stack_size - set and get default stack size
48 * Function: pseudothread_get_stack_size
50 * @code{pseudothread_set_stack_size} sets the stack
51 * size for newly created threads. The default stack size
54 * @code{pseudothread_get_stack_size} returns the current
57 * See also: @ref{new_pseudothread(3)}.
59 extern int pseudothread_set_stack_size (int size);
60 extern int pseudothread_get_stack_size (void);
62 /* Function: new_pseudothread - lightweight "pseudothreads" library
64 * Function: pseudothread_get_threads
65 * Function: pseudothread_count_threads
67 * Pseudothreads are lightweight, cooperatively scheduled threads.
69 * @code{new_pseudothread} creates a new pseudothread. The thread
70 * only starts running when you call @code{pth_start}. The @code{pool}
71 * argument passed is used for all allocations within the thread.
72 * This pool is automatically deleted when the thread exits.
73 * The @code{name} argument is the name of the thread (used in
74 * thread listings -- see @ref{pseudothread_get_threads(3)}). You
75 * may change the name later. The @code{run} and @code{data}
76 * arguments are the entry point into the thread. The entry
77 * point is called as @code{run (data)}.
79 * @code{pseudothread_get_threads} returns a list of all the
80 * currently running pseudothreads. This allows you to implement
81 * a "process listing" for a program. The returned value
82 * is a vector of pseudothread structures (not pointers). These
83 * structures are opaque to you, but you can call the pth_get_*
84 * functions on the address of each one.
86 * @code{pseudothread_count_threads} counts the number of currently
89 extern pseudothread new_pseudothread (pool, void (*run) (void *), void *data, const char *name);
90 extern void pth_start (pseudothread pth);
91 extern vector pseudothread_get_threads (pool);
92 extern int pseudothread_count_threads (void);
94 /* Function: pth_accept - pseudothread system calls
95 * Function: pth_connect
99 * Function: pth_millisleep
100 * Function: pth_nanosleep
101 * Function: pth_timeout
103 * @code{pth_accept}, @code{pth_connect}, @code{pth_read}, @code{pth_write},
104 * @code{pth_sleep} and @code{pth_nanosleep} behave just like the
105 * corresponding system calls. However these calls handle non-blocking
106 * sockets and cause the thread to sleep on the reactor if it would
107 * block. For general I/O you will probably wish to wrap up your
108 * sockets in I/O handle objects, which give you a higher-level
109 * buffered interface to sockets (see @ref{io_fdopen(3)}).
111 * @code{pth_millisleep} sleeps for a given number of milliseconds.
113 * @code{pth_timeout} is similar to the @ref{alarm(2)} system call: it
114 * registers a timeout (in seconds). The thread will exit automatically
115 * (even in the middle of a system call) if the timeout is reached.
116 * To reset the timeout, call @code{pth_timeout} with a timeout of 0.
118 * See also: @ref{pth_poll(3)}, @ref{pth_select(3)}.
120 extern int pth_accept (int, struct sockaddr *, int *);
121 extern int pth_connect (int, struct sockaddr *, int);
122 extern ssize_t pth_read (int, void *, size_t);
123 extern ssize_t pth_write (int, const void *, size_t);
124 extern int pth_sleep (int seconds);
125 extern int pth_millisleep (int millis);
126 extern int pth_nanosleep (const struct timespec *req, struct timespec *rem);
127 extern void pth_timeout (int seconds);
129 /* Function: pth_send - pseudothread network system calls
130 * Function: pth_sendto
131 * Function: pth_sendmsg
133 * Function: pth_recvfrom
134 * Function: pth_recvmsg
136 * @code{pth_send}, @code{pth_sendto}, @code{pth_sendmsg},
137 * @code{pth_recv}, @code{pth_recvfrom} and @code{pth_recvmsg}
138 * behave just like the corresponding system calls. However
139 * these calls handle non-blocking sockets and cause the
140 * thread to sleep on the reactor if it would block.
142 * See also: @ref{pth_poll(3)}, @ref{pth_read(3)}, @ref{pth_write(3)}.
144 extern int pth_send (int s, const void *msg, int len, unsigned int flags);
145 extern int pth_sendto (int s, const void *msg, int len, unsigned int flags, const struct sockaddr *to, int tolen);
146 extern int pth_sendmsg (int s, const struct msghdr *msg, unsigned int flags);
147 extern int pth_recv (int s, void *buf, int len, unsigned int flags);
148 extern int pth_recvfrom (int s, void *buf, int len, unsigned int flags, struct sockaddr *from, int *fromlen);
149 extern int pth_recvmsg (int s, struct msghdr *msg, unsigned int flags);
151 /* Function: pth_poll - pseudothread poll and select system calls
152 * Function: pth_select
154 * @code{pth_poll} behaves like the @ref{poll(2)} system call. It
155 * specifies an array @code{n} of @code{fds} file descriptor structures
156 * each of which is checked for an I/O event. If @code{timeout} is
157 * greater than or equal to zero, then the call will return after
158 * this many milliseconds if no I/O events are detected. If @code{timeout}
159 * is negative, then the timeout is infinite.
161 * @code{pth_select} behaves like the @ref{select(2)} system call.
163 * Note that @code{pth_select} is implemented as a library on top
164 * of @code{pth_poll}, and is considerably less efficient than
165 * @code{pth_poll}. It is recommended that you rewrite any code
166 * which uses @code{pth_select}/@code{select} to use
167 * @code{pth_poll}/@code{poll} instead.
169 * See also: @ref{pth_timeout(3)}, @ref{pth_wait_readable(3)}.
171 extern int pth_poll (struct pollfd *fds, unsigned int n, int timeout);
172 extern int pth_select (int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);
174 /* Function: pth_wait_readable - wait for a file descriptor to become readable or writable
175 * Function: pth_wait_writable
177 * @code{pth_wait_readable} waits until a given file descriptor (or
178 * socket) has data to read.
180 * @code{pth_wait_writable} waits until a given file descriptor (or
181 * socket) can be written without blocking.
183 * The @code{fd} must be set to non-blocking.
185 * Returns: Both functions return 0 if OK, or -1 if there was an error.
187 * See also: @ref{pth_poll(3)}.
189 extern int pth_wait_readable (int fd);
190 extern int pth_wait_writable (int fd);
192 /* Function: pth_exit - exit a pseudothread and exception handling
194 * Function: pth_catch
196 * @code{pth_exit} causes the current thread to exit immediately.
198 * @code{pth_die} is similar in concept to @code{pth_exit}, except
199 * that it throws an exception which may be caught by using the
200 * @code{pth_catch} function. The distinction between @code{pth_die}
201 * and @code{pth_exit} is the same as the distinction between
202 * the Perl functions @code{die} and @code{exit}, in as much as
203 * @code{exit} in Perl always exits the process immediately, and
204 * @code{die} in Perl generally exits the process immediately
205 * unless the programmer catches the exception with @code{eval}
206 * and handles it appropriately.
208 * @code{pth_catch} is used to catch exceptions thrown by
209 * @code{pth_die}. You give @code{fn} (function) and @code{data}
210 * arguments, and the function calls @code{fn (data)}. If, during
211 * this call, the code calls @code{pth_die}, then the exception
212 * message is immediately returned from @code{pth_catch}. If
213 * the code runs successfully to completion, then @code{pth_catch}
214 * will return @code{NULL}.
216 * Exceptions may be nested.
218 * Note that @code{pth_catch} will not catch calls to @code{pth_exit}.
220 extern void pth_exit (void) __attribute__((noreturn));
221 #define pth_die(msg) _pth_die ((msg), __FILE__, __LINE__)
222 extern const char *pth_catch (void (*fn) (void *), void *data);
224 extern void _pth_die (const char *msg,
225 const char *filename, int lineno)
226 __attribute__((noreturn));
228 /* Function: pth_get_pool - get and set status of pseudothreads
229 * Function: pth_get_name
230 * Function: pth_get_thread_num
231 * Function: pth_get_run
232 * Function: pth_get_data
233 * Function: pth_get_language
234 * Function: pth_get_tz
235 * Function: pth_get_stack
236 * Function: pth_get_stack_size
237 * Function: pth_get_PC
238 * Function: pth_get_SP
239 * Function: pth_set_name
240 * Function: pth_set_language
241 * Function: pth_set_tz
243 * @code{pth_get_pool} returns the pool associated with this thread.
244 * The thread should use this pool for all allocations, ensuring that
245 * they are cleaned up correctly when the thread is deleted. See
248 * @code{pth_get_name} returns the name of the thread. Note that
249 * this string is normally stored in thread's local pool, and therefore
250 * the string memory may be unexpected deallocated if the thread
251 * exits. Callers should take a copy of the string in their own pool
252 * if they are likely to need the string for a long period of time.
254 * @code{pth_get_thread_num} returns the thread number (roughly
255 * the equivalent of a process ID).
257 * @code{pth_get_run} and @code{pth_get_data} return the original
258 * entry point information of the thread.
260 * @code{pth_get_language} returns the value of the @code{LANGUAGE}
261 * environment variable for this thread. See the discussion
262 * of @code{pth_set_language} below.
264 * @code{pth_get_language} returns the value of the @code{TZ}
265 * environment variable for this thread. See the discussion
266 * of @code{pth_set_tz} below.
268 * @code{pth_get_stack} returns the top of the stack for this
271 * @code{pth_get_stack_size} returns the maximum size of the stack for
274 * @code{pth_get_PC} returns the current program counter (PC) for
275 * this thread. Obviously it only makes sense to call this from
278 * @code{pth_get_SP} returns the current stack pointer (SP) for
279 * this thread. Obviously it only makes sense to call this from
282 * @code{pth_set_name} changes the name of the thread. The string
283 * @code{name} argument passed must be either statically allocated,
284 * or allocated in the thread's own pool (the normal case), or else
285 * allocated in another pool with a longer life than the current
288 * @code{pth_set_language} changes the per-thread @code{LANGUAGE}
289 * environment variable. This is useful when serving clients from
290 * multiple locales, and using GNU gettext for translation.
292 * @code{pth_set_tz} changes the per-thread @code{TZ}
293 * environment variable. This is useful when serving clients from
294 * multiple timezones, and using @code{localtime} and related
297 extern pool pth_get_pool (pseudothread pth);
298 extern const char *pth_get_name (pseudothread pth);
299 extern int pth_get_thread_num (pseudothread pth);
300 extern void (*pth_get_run (pseudothread pth)) (void *);
301 extern void *pth_get_data (pseudothread pth);
302 extern const char *pth_get_language (pseudothread pth);
303 extern const char *pth_get_tz (pseudothread pth);
304 extern void *pth_get_stack (pseudothread pth);
305 extern int pth_get_stack_size (pseudothread pth);
306 extern unsigned long pth_get_PC (pseudothread pth);
307 extern unsigned long pth_get_SP (pseudothread pth);
308 extern void pth_set_name (const char *name);
309 extern void pth_set_language (const char *lang);
310 extern void pth_set_tz (const char *tz);
312 /* These low-level functions are used by other parts of the pthrlib library.
313 * Do not use them from user programs. They switch thread context with the
314 * calling context and v.v.
316 extern void _pth_switch_thread_to_calling_context (void);
317 extern void _pth_switch_calling_to_thread_context (pseudothread new_pth);
318 extern int _pth_alarm_received (void);
320 #endif /* PTHR_PSEUDOTHREAD_H */