nthm_send - start a new thread with no return value needed
#include <nthm/nthm.h>
int nthm_send ( nthm_slacker &mutator , void * operand , int * err )
The mutator argument is a pointer to a function that takes a void pointer and has no return value. Compatible function pointers can be cast as such by the nthm_slacker type alias. The function nthm_send passes operand to mutator as if the caller had invoked
mutator ( operand );
but runs mutator 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.
The mutator function must not call pthread_exit. Its thread will terminate automatically after the function returns.
Zero is returned if nthm_send is unsuccessful for any reason. A non-zero value is returned otherwise.
The *err parameter is assigned a non-zero error code by nthm_send if it is zero on entry and if an error is detected, but is left unchanged otherwise. If nthm_send detects an error, then the mutator function is not executed. These error codes among others are possible for the reasons shown.
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.
Other values corresponding to POSIX errors or nthm internal errors in the range of -NTHM_MIN_ERR to -NTHM_MAX_ERR might also be assigned. Internal errors may indicate memory corruption, misuse of the API, or a bug in nthm. Bug reports including error codes are welcome.
An application program containing this fragment sleeps for at least one second after a successful call to nthm_send despite the main thread exiting immediately thereafter.
void f (void *x)
{
sleep (1);
}
// ... main thread below
err = 0;
nthm_send ((nthm_slacker) &f, x, &err);
if (err)
printf ("%s\\n", nthm_strerror (err));
exit (err ? EXIT_FAILURE : EXIT_SUCCESS);
This function is an alternative to the standard pthread_create function that is less configurable but behaves more in line with expectations.
The best use of nthm_send is for background operations whose completion is not a prerequisite for anything but termination, such as reclaiming storage or closing sockets and files, and that do not use any resources held by the main application thread.
If a thread created by nthm_send needs access to a resource planned to be released in the main thread, such as an open file handle or a pointer to the heap, then the code that releases it should be run either in an exit routine installed by the standard atexit (3) utility prior to the first call to any nthm library function, or after a call to nthm_sync. Otherwise, there is no assurance of the resource persisting until the thread needs it.
Threads created by nthm_send are not affected by nthm_kill_all or nthm_truncate_all except insofar nthm_send fails when called in a killed thread. If nthm_killed or nthm_truncated is called in the context of a thread created by nthm_send, it will return zero.
On 64-bit systems, use this command to display the default stack size in Kbytes.
ulimit -s
nthm, nthm_open, 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), atexit (3)
Dennis Furey (milonga@delayinsensitive.com)
https://github.com/gueststar/nthm