NAME

nthm_select - return a pipe from the next thread to finish

SYNOPSIS

#include <nthm/nthm.h>

nthm_pipe nthm_select ( int *err )

DESCRIPTION

The nthm_select function obtains a pipe whose return value is ready to be read. The pipe is selected from among those previously opened with nthm_open in the context the caller's thread, or previously tethered to it with nthm_tether. If multiple scopes exist in the caller's thread due to previous calls to nthm_enter_scope, the pipe is selected only from among those opened or tethered in the most recently entered scope.

Interleaved calls to nthm_open, nthm_select and nthm_read are an efficient way to run a pool of worker threads without unnecessary blocking because nthm_select never blocks unless there is no alternative due to all threads in the current scope being busy.

Applications can check whether a call to nthm_select would block by polling nthm_blocked.

RETURN VALUE

Each successful call to nthm_select returns a fresh pipe previously opened within the caller's context and scope by nthm_open or tethered to it by nthm_tether until there are none left, at which time nthm_select returns NULL. If more pipes are opened or tethered later, then they will be available via subsequent calls to nthm_select.

An unsuccessful call to nthm_select also returns a NULL result. Whether a NULL result indicates a successful call when there are no more pipes or an unsuccessful call can be determined by the error code as explained below.

Any pipe returned by nthm_select is guaranteed to be readable by nthm_read without blocking the caller.

• If no pipe is available for reading without blocking but there is at least one pipe whose thread is still running, then nthm_select blocks the caller until the next thread finishes and only then returns its pipe.
• If multiple pipes are ready for reading without blocking, then nthm_select returns the one that has been ready the longest and saves the rest for subsequent calls.

ERRORS

Error codes are reported in *err with any non-zero value indicating an error. If *err is non-zero on entry, then nthm_select leaves it unchanged. If it is zero on entry and non-zero on exit, then nthm_select may set *err to following code for the reason noted.

NTHM_KILLED

Selecting was interrupted because the caller's thread was killed with nthm_kill or nthm_kill_all.

Undocumented error codes also may be assigned to *err if internal consistency checks fail, which are helpful in bug reports.

SEE ALSO

nthm, nthm_open, nthm_send, nthm_read, 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

AUTHOR

Dennis Furey (milonga@delayinsensitive.com)

PROJECT PAGE

https://github.com/gueststar/nthm