src/pthr_pseudothread.h

   1 /* Pseudothread handler.
   2  *
   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.
   7  *
   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.
  12  *
  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.
  16  *
  17  * $Id: pthr_pseudothread.h,v 1.13 2002/12/01 14:29:30 rich Exp $
  18  */
  19
  20 #ifndef PTHR_PSEUDOTHREAD_H
  21 #define PTHR_PSEUDOTHREAD_H
  22
  23 #include <stdlib.h>
  24
  25 #include <sys/types.h>
  26 #include <unistd.h>
  27 #include <sys/socket.h>
  28 #include <setjmp.h>
  29 #include <time.h>
  30
  31 #include <pool.h>
  32 #include <vector.h>
  33
  34 #include "pthr_reactor.h"
  35 #include "pthr_context.h"
  36
  37 struct pseudothread;
  38 typedef struct pseudothread *pseudothread;
  39
  40 /* Function: current_pth - current pseudothread
  41  *
  42  * @code{current_pth} is a global variable containing the currently
  43  * running thread.
  44  */
  45 extern pseudothread current_pth;
  46
  47 /* Function: pseudothread_set_stack_size - set and get default stack size
  48  * Function: pseudothread_get_stack_size
  49  *
  50  * @code{pseudothread_set_stack_size} sets the stack
  51  * size for newly created threads. The default stack size
  52  * is 64 KBytes.
  53  *
  54  * @code{pseudothread_get_stack_size} returns the current
  55  * stack size setting.
  56  *
  57  * See also: @ref{new_pseudothread(3)}.
  58  */
  59 extern int pseudothread_set_stack_size (int size);
  60 extern int pseudothread_get_stack_size (void);
  61
  62 /* Function: new_pseudothread - lightweight "pseudothreads" library
  63  * Function: pth_start
  64  * Function: pseudothread_get_threads
  65  * Function: pseudothread_count_threads
  66  *
  67  * Pseudothreads are lightweight, cooperatively scheduled threads.
  68  *
  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)}.
  78  *
  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.
  85  *
  86  * @code{pseudothread_count_threads} counts the number of currently
  87  * running threads.
  88  */
  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);
  93
  94 /* Function: pth_accept - pseudothread system calls
  95  * Function: pth_connect
  96  * Function: pth_read
  97  * Function: pth_write
  98  * Function: pth_sleep
  99  * Function: pth_millisleep
 100  * Function: pth_nanosleep
 101  * Function: pth_timeout
 102  *
 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)}).
 110  *
 111  * @code{pth_millisleep} sleeps for a given number of milliseconds.
 112  *
 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.
 117  *
 118  * See also: @ref{pth_poll(3)}, @ref{pth_select(3)}.
 119  */
 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);
 128
 129 /* Function: pth_send - pseudothread network system calls
 130  * Function: pth_sendto
 131  * Function: pth_sendmsg
 132  * Function: pth_recv
 133  * Function: pth_recvfrom
 134  * Function: pth_recvmsg
 135  *
 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.
 141  *
 142  * See also: @ref{pth_poll(3)}, @ref{pth_read(3)}, @ref{pth_write(3)}.
 143  */
 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);
 150
 151 /* Function: pth_poll - pseudothread poll and select system calls
 152  * Function: pth_select
 153  *
 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.
 160  *
 161  * @code{pth_select} behaves like the @ref{select(2)} system call.
 162  *
 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.
 168  *
 169  * See also: @ref{pth_timeout(3)}, @ref{pth_wait_readable(3)}.
 170  */
 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);
 173
 174 /* Function: pth_wait_readable - wait for a file descriptor to become readable or writable
 175  * Function: pth_wait_writable
 176  *
 177  * @code{pth_wait_readable} waits until a given file descriptor (or
 178  * socket) has data to read.
 179  *
 180  * @code{pth_wait_writable} waits until a given file descriptor (or
 181  * socket) can be written without blocking.
 182  *
 183  * The @code{fd} must be set to non-blocking.
 184  *
 185  * Returns: Both functions return 0 if OK, or -1 if there was an error.
 186  *
 187  * See also: @ref{pth_poll(3)}.
 188  */
 189 extern int pth_wait_readable (int fd);
 190 extern int pth_wait_writable (int fd);
 191
 192 /* Function: pth_exit - exit a pseudothread and exception handling
 193  * Function: pth_die
 194  * Function: pth_catch
 195  *
 196  * @code{pth_exit} causes the current thread to exit immediately.
 197  *
 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.
 207  *
 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}.
 215  *
 216  * Exceptions may be nested.
 217  *
 218  * Note that @code{pth_catch} will not catch calls to @code{pth_exit}.
 219  */
 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);
 223
 224 extern void _pth_die (const char *msg,
 225                       const char *filename, int lineno)
 226      __attribute__((noreturn));
 227
 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
 242  *
 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
 246  * @ref{new_pool(3)}.
 247  *
 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.
 253  *
 254  * @code{pth_get_thread_num} returns the thread number (roughly
 255  * the equivalent of a process ID).
 256  *
 257  * @code{pth_get_run} and @code{pth_get_data} return the original
 258  * entry point information of the thread.
 259  *
 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.
 263  *
 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.
 267  *
 268  * @code{pth_get_stack} returns the top of the stack for this
 269  * thread.
 270  *
 271  * @code{pth_get_stack_size} returns the maximum size of the stack for
 272  * this thread.
 273  *
 274  * @code{pth_get_PC} returns the current program counter (PC) for
 275  * this thread. Obviously it only makes sense to call this from
 276  * another thread.
 277  *
 278  * @code{pth_get_SP} returns the current stack pointer (SP) for
 279  * this thread. Obviously it only makes sense to call this from
 280  * another thread.
 281  *
 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
 286  * thread.
 287  *
 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.
 291  *
 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
 295  * functions.
 296  */
 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);
 311
 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.
 315  */
 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);
 319
 320 #endif /* PTHR_PSEUDOTHREAD_H */