X-Git-Url: http://git.pond.sub.org/?p=empserver;a=blobdiff_plain;f=include%2Fempthread.h;h=4bdcf444cc6881e79a52edbf757088605bc27413;hp=219ddb3ad7afdbcfbefd845912b67d0ce6b2822a;hb=HEAD;hpb=d052239a7a5600b4cb3a468438c4f3d47c6aac34 diff --git a/include/empthread.h b/include/empthread.h index 219ddb3ad..4bdcf444c 100644 --- a/include/empthread.h +++ b/include/empthread.h @@ -1,11 +1,11 @@ /* * Empire - A multi-player, client/server Internet based war game. - * Copyright (C) 1986-2009, Dave Pare, Jeff Bailey, Thomas Ruschak, - * Ken Stevens, Steve McClure + * Copyright (C) 1986-2021, Dave Pare, Jeff Bailey, Thomas Ruschak, + * Ken Stevens, Steve McClure, Markus Armbruster * - * This program is free software; you can redistribute it and/or modify + * Empire is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or + * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, @@ -14,8 +14,7 @@ * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * along with this program. If not, see . * * --- * @@ -31,7 +30,7 @@ * Sasha Mikheev * Doug Hay, 1998 * Steve McClure, 1998 - * Markus Armbruster, 2005-2008 + * Markus Armbruster, 2005-2012 * Ron Koenderink, 2005-2009 */ @@ -56,7 +55,7 @@ /* Abstract data types */ -/* A thread. */ +/* A thread. */ typedef struct lwpProc empth_t; /* A read-write lock, perferring writers */ @@ -102,8 +101,8 @@ void empth_request_shutdown(void); /* * Initialize thread package. - * CTX points to a thread context variable; see empth_create(). - * FLAGS request optional features. + * @ctx points to a thread context variable; see empth_create(). + * @flags request optional features. * Should return 0 on success, -1 on error, but currently always * returns 0. */ @@ -111,12 +110,12 @@ int empth_init(void **ctx, int flags); /* * Create a new thread. - * ENTRY is the entry point. It will be called with argument UD. + * @entry is the entry point. It will be called with argument @ud. * If it returns, the thread terminates as if it called empth_exit(). - * Thread stack is at least SIZE bytes. - * FLAGS should be the same as were passed to empth_init(), or zero. - * NAME is the thread's name, it is used for logging and debugging. - * UD is the value to pass to ENTRY. It is also assigned to the + * Thread stack is at least @size bytes. + * @flags should be the same as were passed to empth_init(), or zero. + * @name is the thread's name, it is used for logging and debugging. + * @ud is the value to pass to @entry. It is also assigned to the * context variable defined with empth_init() whenever the thread gets * scheduled. * Yield the processor. @@ -126,17 +125,18 @@ empth_t *empth_create(void (*entry)(void *), int size, int flags, char *name, void *ud); /* - * Return the current thread. + * Return the current thread, NULL before empth_init(). + * This is the only function that may be called before empth_init(). */ empth_t *empth_self(void); /* - * Return the name THREAD. + * Return @thread's name. */ char *empth_name(empth_t *thread); /* - * Set the name of THREAD to NAME. + * Set @thread's name to @name. */ void empth_set_name(empth_t *thread, char *name); @@ -155,51 +155,52 @@ void empth_exit(void); void empth_yield(void); /* - * Put current thread to sleep until file descriptor FD is ready for I/O. - * If FLAGS & EMPTH_FD_READ, wake up if FD is ready for input. - * If FLAGS & EMPTH_FD_WRITE, wake up if FD is ready for output. + * Put current thread to sleep until file descriptor @fd is ready for I/O. + * If @flags & EMPTH_FD_READ, wake up if @fd is ready for input. + * If @flags & EMPTH_FD_WRITE, wake up if @fd is ready for output. * At most one thread may sleep on the same file descriptor. - * TIMEOUT, if non-null, limits the sleep time. - * Return one when the FD is ready, zero on timeout or early wakeup by + * @timeout, if non-null, limits the sleep time. + * Return one when the @fd is ready, zero on timeout or early wakeup by * empth_wakeup(), -1 on error with errno set. - * Note: Currently, Empire sleeps only on network I/O, i.e. FD is a + * Note: Currently, Empire sleeps only on network I/O, i.e. @fd is a * socket. Implementations should not rely on that. */ int empth_select(int fd, int flags, struct timeval *timeout); /* - * Awaken THREAD if it is sleeping in empth_select() or empth_sleep(). + * Awaken @thread if it is sleeping in empth_select() or empth_sleep(). * This does not awaken threads sleeping in other functions. * Does not yield the processor. */ void empth_wakeup(empth_t *thread); /* - * Put current thread to sleep until the time is UNTIL. + * Put current thread to sleep until the time is @until. * Return 0 if it slept until that time. * Return -1 if woken up early, by empth_wakeup(). */ int empth_sleep(time_t until); /* - * Wait for signal, return the signal number. + * Put current thread to sleep until SIGHUP, SIGINT or SIGTERM is received. + * Return the signal number. */ int empth_wait_for_signal(void); /* * Create a read-write lock. - * NAME is its name, it is used for debugging. + * @name is its name, it is used for debugging. * Return the read-write lock, or NULL on error. */ empth_rwlock_t *empth_rwlock_create(char *name); /* - * Destroy RWLOCK. + * Destroy @rwlock. */ void empth_rwlock_destroy(empth_rwlock_t *rwlock); /* - * Lock RWLOCK for writing. + * Lock @rwlock for writing. * A read-write lock can be locked for writing only when it is * unlocked. If this is not the case, put the current thread to sleep * until it is. @@ -207,7 +208,7 @@ void empth_rwlock_destroy(empth_rwlock_t *rwlock); void empth_rwlock_wrlock(empth_rwlock_t *rwlock); /* - * Lock RWLOCK for reading. + * Lock @rwlock for reading. * A read-write lock can be locked for reading only when it is not * locked for writing, and no other thread is attempting to lock it * for writing. If this is not the case, put the current thread to @@ -216,8 +217,8 @@ void empth_rwlock_wrlock(empth_rwlock_t *rwlock); void empth_rwlock_rdlock(empth_rwlock_t *rwlock); /* - * Unlock read-write lock RWLOCK. - * The current thread must hold RWLOCK. + * Unlock read-write lock @rwlock. + * The current thread must hold @rwlock. * Wake up threads that can now lock it. */ void empth_rwlock_unlock(empth_rwlock_t *rwlock);