nthm_tether - start watching a given thread from the current thread
nthm_untether - stop watching a given thread from the current thread
#include <nthm/nthm.h>
void nthm_tether ( nthm_pipe source , int *err )
void nthm_untether ( nthm_pipe source , int *err )
Threads managed by the nthm library may be envisioned as forming a tree in which some are descendents of others. Whenever an application creates a thread by calling nthm_open, the created thread becomes a descendent of the caller's thread. Functions such as nthm_select, nthm_blocked, nthm_kill_all, and nthm_truncate_all rely on this relationship to operate on the descendents of the caller's thread or to query them.
The nthm_tether and nthm_untether functions allow applications explicit control over this tree. Whenever nthm_untether is called on a pipe source whose thread is currently a descendent of the caller's thread, it stops being a descendent of the caller's thread, thereafter to be ignored by the functions mentioned above.
Whereas tethered threads are automatically killed when the thread above them in the tree terminates, nothing precludes the pipe of an untethered thread being passed via the return value on termination or in the input data when a new pipe is opened. Application code running in the receiving thread may then call nthm_tether to acheive the same effect as having opened it locally.
none
If *err is non-zero on entry, then nthm_tether and nthm_untether leave it unchanged. If *err is zero on entry and non-zero on exit, it may be assigned one of the following values for the reasons noted, and the requested operation will not have completed.
NTHM_NULPIP
The source parameter is a NULL pointer.
NTHM_INVPIP
The source parameter is not a NULL pointer but points to an invalid or corrupted pipe, or points nowhere in particular but fortunately did not cause a segfault.
NTHM_NOTDRN
The caller can neither tether nor untether the source pipe's thread to the caller's thread because it is tethered presently to some other thread than that of the caller.
NTHM_KILLED
The nthm_tether function was interrupted because the caller's thread was killed. It may have been killed directly with nthm_kill or nthm_kill_all or as a consequence of a thread to which it is tethered being killed or terminating.
ENOMEM
Available memory is insufficient for all updates necessary to nthm_tether.
Various undocumented error codes within the range of -NTHM_MIN_ERR to -NTHM_MAX_ERR might also be reported for developer diagnostics if internal consistency checks fail. These codes are not actionable by users but may be helpful in bug reports.
nthm, nthm_open, 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_blocked, nthm_strerror, nthm_busy, pthreads (7), nthm_sync
Dennis Furey (milonga@delayinsensitive.com)
https://github.com/gueststar/nthm