nthm_open - start a new thread and return a pipe from it
#include <nthm/nthm.h>
nthm_pipe nthm_open ( nthm_worker &operator , void *operand , int *err )
The operator argument is a function that takes a void pointer and an int pointer and returns a void pointer. Compatible functions can be cast as such by the nthm_worker type alias. The function nthm_open passes the parameters operand and err to operator as if the caller had invoked
retval = operator ( operand , err )
but runs operator in a separate thread from the caller. On 32-bit systems, the usable stack size allocated to the created thread is limited to NTHM_STACK_MIN or roughly 16 Kbytes with a view to conserving virtual address space. On 64-bit systems, the default stack size (typically 8MB) is reserved but not physically used unless the thread's stack actually grows to that size.
When operator returns its result, the thread created for it exits. The operator function must *not* call pthread_exit explicitly. If operator assigns an error code to *err, the error code is available to the reader of the pipe returned by nthm_open. To avoid ambiguity, operator should avoid assigning error codes that clash with those noted below.
If nthm_open does not succeed, it returns NULL and operator is not run.
If nthm_open succeeds, it returns a value of type nthm_pipe that may be used in subsequent calls to nthm_read, nthm_truncate, nthm_kill, nthm_untether, nthm_tether, and nthm_busy. For example,
my_pipe = nthm_open ((nthm_worker) &my_function, &some_data, err); // ... retval = nthm_read (my_pipe, err);
If *err is zero on entry and nthm_open does not succeed, it assigns a non-zero number to *err. Otherwise, it leaves *err unchanged. Negative numbers from -NTHM_MIN_ERR to -NTHM_MAX_ERR report internal errors. Internal errors may be due to memory corruption, misuse of the API, or a bug in nthm. (Bug reports are welcome.) Positive numbers report POSIX errors. The following specific errors are possible.
EAGAIN
Resources or permission are insufficient to create a thread.
ENOMEM
There is insufficient memory for a new thread or metadata.
NTHM_KILLED
No new threads may be created because the caller's thread has been killed. The thread may have been killed directly by its creator with nthm_kill or nthm_kill_all or indirectly due to the creator being killed or exiting.
On 64-bit systems, use this command to display the default stack size in Kbytes.
ulimit -s
nthm, nthm_send, nthm_read, nthm_select, nthm_truncate, nthm_truncate_all, nthm_truncated, nthm_enter_scope, nthm_exit_scope, nthm_kill, nthm_kill_all, nthm_killed, nthm_untether, nthm_tether, nthm_blocked, nthm_busy, nthm_sync, nthm_strerror, pthreads (7), ulimit (1)
Dennis Furey (milonga@delayinsensitive.com)
https://github.com/gueststar/nthm