NAME

nthm_kill - request shutdown of a given thread

nthm_killed - poll the liveness status of the current thread

SYNOPSIS

#include <nthm/nthm.h>

void nthm_kill ( nthm_pipe source , int *err )

int nthm_killed ( int *err )

DESCRIPTION

Calling nthm_kill on a pipe source has these effects on the application code running in the thread associated with the pipe:

• Any blocking call to nthm_read or nthm_select in progress is interrupted immediately and an error status of NTHM_KILLED applies.
• Eventually, subsequent calls to functions nthm_open, nthm_send, nthm_read, nthm_select, nthm_tether, and nthm_enter_scope are disabled with status NTHM_KILLED.
• The nthm_killed function returns a non-zero result when polled.
• The result the application returns and error status it sets on exit are inaccessible and ignored.

The best thing for the application code in a killed thread to do is to shut down in some orderly way appropriate for the application, such as by releasing any resources it holds. However, it need not kill any threads tethered to itself because they are killed automatically on exit.

Orderly shutdowns notwithstanding, careless use of nthm_kill incurs a risk of memory leaks when reading of heap-allocated storage is interrupted or ignored. The risk is mitigated by not using nthm_kill on threads whose pipes may convey pointers to otherwise unreachable memory. Consider nthm_truncate as an alternative.

It is an error to call nthm_kill more than once with the same source or to make any further reference to the killed source afterwards.

RETURN VALUE

There is no return value for nthm_kill, but a successful call to nthm_killed returns non-zero if the current thread has been killed and zero otherwise. An unsuccessful call to nthm_killed always returns zero.

ERRORS

Error codes are reported in the *err parameter, with any non-zero value indicating an error.

• If *err is non-zero on entry, then it is left unchanged whether or not the function succeeds.
• If *err is zero on entry and exit, then nthm_kill or nthm_killed has succeeded.
• If *err is zero on entry and non-zero on exit, then the function has not succeeded and one of the following codes may be reported due to the respective condition.

NTHM_NULPIP

The source is a NULL pointer.

NTHM_INVPIP

The source 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 source thread is not safe to kill because the caller's thread is not its "drain", which can happen only if source was opened in a thread other than the current one and not untethered from it or opened in the same thread but in a different scope as determined by nthm_enter_scope.

Any other error code not present intially indicates either a bug in nthm or an attempt to kill the same pipe more than once. Bug reports are gratefully received.

SEE ALSO

nthm, nthm_open, nthm_send, nthm_select, nthm_read, nthm_truncate, nthm_truncated, nthm_truncate_all, nthm_enter_scope, nthm_exit_scope, nthm_kill_all, nthm_blocked, nthm_busy, nthm_untether, nthm_tether, nthm_strerror, nthm_sync

AUTHOR

Dennis Furey (milonga@delayinsensitive.com)

PROJECT PAGE

https://github.com/gueststar/nthm