NAME

nthm_truncate - tell a thread to finish up by approximating its output

nthm_truncated - poll the current thread's the truncation status

SYNOPSIS

#include <nthm/nthm.h>

void nthm_truncate ( nthm_pipe source , int *err )

int nthm_truncated ( int * err )

DESCRIPTION

The nthm_truncate function informs a thread created by nthm_open and associated with the pipe source that it should return a result sooner than usual by computing an approximate solution. Application code running in the source thread can detect that truncated output has been requested by polling nthm_truncated. The application is free to ignore or to interpret this condition in any user-specified way.

After the source thread is truncated, nthm_truncated will be able to report this status not only to code running in the source thread but to code running in any thread it creates or has created with nthm_open unless and until the latter is untethered with nthm_untether. The same goes for threads created in threads created in the source thread, and so on.

It is acceptable to call nthm_truncate more than once with the same source as a way of indicating increasingly emphatic degrees of truncation. Each additional call increments the value reportable by nthm_truncated. However, if a thread is a descendent of multiple ancestors with different degrees of truncation, nthm_truncated reports only the value associated with the nearest truncated ancestor.

RETURN VALUE

There is no return value from nthm_truncate, but nthm_truncated returns a value indicative of the current thread's truncation status up to a platform-specific maximum of UINT_MAX or at least 4294967295.

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_truncate or nthm_truncated 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 truncate 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 a misuse of the API. Bug reports are appreciated.

SEE ALSO

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

AUTHOR

Dennis Furey (milonga@delayinsensitive.com)

PROJECT PAGE

https://github.com/gueststar/nthm