nthm_read - read a result from a pipe and reclaim the pipe
#include <nthm/nthm.h>
void * nthm_read ( nthm_pipe source , int *err )
The nthm_read function is used for collecting the results computed in threads created by nthm_open. The source parameter should be an nthm_pipe returned from a prior call to nthm_open or nthm_select.
If the pipe's thread is still running when nthm_read is called, the caller is blocked until the thread finishes. If the thread has finished running beforehand, then nthm_read immediately reads its return value and returns it to the caller.
Pipes returned by nthm_select are always readable immediately although nthm_select itself may sometimes block. Applications can check whether a call to nthm_read would block by polling nthm_blocked with the same source, and can check whether nthm_select would block by polling nthm_busy.
The source parameter is deallocated upon return from nthm_read. Any subsequent reference to it has undefined effects.
If nthm_read does not succeed, it returns a NULL value.
If it succeeds, then it returns the result computed by the application code in the pipe's thread, which may be NULL or non-NULL depending on the application.
For well-behaved applications, NULL return values can be disambiguated by the error code assigned to the *err parameter.
If *err is zero on entry and nthm_read succeeds, then *err is set by the application code whose pipe has been read. If the application returns a NULL value and also sets *err to a non-zero value, it can avoid giving the impression that nthm_read has not succeeded by using error codes that differ from those listed below and any within the range of -NTHM_MIN_ERR to -NTHM_MAX_ERR.
If *err is non-zero on entry, then nthm_read leaves it unchanged. Any error status reported by the application is inaccessible in this case although nthm_read still returns the application code's return value if successful.
If *err is zero on entry and nthm_read does not succeed, then it may set *err to one of the following codes for the reasons noted.
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 source pipe is not safely readable because the caller's thread is not its "drain", which can happen only if either source was opened in a separate thread from the caller and not untethered from it, or if it was opened in the same thread but in an enclosing scope as determined by nthm_enter_scope.
NTHM_KILLED
Reading was interrupted because the caller's thread was killed with nthm_kill or nthm_kill_all.
NTHM_XSCOPE
The application code running in the thread of the source pipe entered at least one scope by nthm_enter_scope without exiting it by nthm_exit_scope. This error is only a warning because nthm behaves in other respects as if the application code had exited the relevant scopes immediately prior to returning. As usual, unread pipes opened within any enclosed scopes are left running untethered rather than being killed when the scopes are exited. If this behavior is not intended, then the application code should be modified accordingly.
ENOMEM
There is insufficient memory to read from a pipe.
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_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_strerror, nthm_busy, pthreads (7), nthm_sync
Dennis Furey (milonga@delayinsensitive.com)
https://github.com/gueststar/nthm