NAME

nthm_enter_scope - select only from subsequently opened pipes

nthm_exit_scope - allow selection of previously opened pipes

SYNOPSIS

#include <nthm/nthm.h>

int nthm_enter_scope ( int *err )

int nthm_exit_scope ( int *err )

DESCRIPTION

These functions are an advanced feature of nthm whose understanding depends on an understanding of nthm_select and other functions. See the NOTES section below for intended use cases.

Normally nthm_select can choose any pipe tethered to the caller's thread, but nthm_enter_scope can restrict it to specific pipes.

• If there are open pipes when nthm_enter_scope is called, and more pipes are opened afterwards, then nthm_select chooses from among only those latter pipes and ignores the former. If the latter are busy, then nthm_select blocks though the former may be ready. If the latter are absent, then nthm_select returns NULL though the former may exist.
• When nthm_exit_scope is called, pipes opened before the previous call to nthm_enter_scope can be selected again by nthm_select.
• Any remaining pipes opened between a call to nthm_enter_scope and the next call to nthm_exit_scope are untethered thereafter from the caller's thread and hence ignored by nthm_select. However, their threads can continue to execute and be readable as normal.

In more general usage, these functions can effect a stack-like configuration of scopes.

• Each call to nthm_enter_scope pushes a new scope, hiding all pipes opened previously.
• Each call to nthm_exit_scope pops a scope, restoring visibility to pipes opened just prior to the matching push but still hiding those opened before the previous unmatched push, if any.

These functions also affect nthm_blocked, nthm_kill_all, and nthm_truncate_all. They behave consistently with nthm_select.

• nthm_blocked returns a non-zero value if nthm_select would block at the point where nthm_blocked is called when scopes are taken into account.
• nthm_kill_all and nthm_truncate_all affect only the pipes that have been opened since the most recent call to nthm_enter_scope not matched by a call to nthm_exit_scope.

The functions nthm_kill, nthm_truncate, nthm_untether, and nthm_read are also affected. Attempts to apply them to pipes that are tethered but not selectable by the above criteria cause the error status of NTHM_NOTDRN, just as if the pipes had been tethered to a different thread.

RETURN VALUE

A non-zero value is returned by nthm_enter_scope and nthm_enter_scope if they succeed.

ERRORS

If *err is non-zero on entry, then nthm_enter_scope and nthm_exit_scope leave it unchanged. If *err is zero on entry and non-zero on exit, it may have been assigned one of the following values for the reasons noted, and the requested operation will not have completed.

NTHM_UNDFLO

A scope underflow status is reported whenever nthm_exit_scope is called more times than nthm_enter_scope.

NTHM_KILLED

The nthm_enter_scope 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.

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.

EXAMPLES

This example illustrates pipes opened in two scopes with explanations of what to expect.

p1 = nthm_open (&f1, &x1, err);
p2 = nthm_open (&f2, &x2, err);

nthm_enter_scope (err);

   q1 = nthm_open (&g1, &y1, err);
   q2 = nthm_open (&g2, &y2, err);

   // A is guaranteed to be read from either q1 or q2.

   A = nthm_read (nthm_select (err), err);

nthm_exit_scope (err);

// The other of q1 or q2 is untethered at this
// point but may continue to run. B is guaranteed
// to be read from either p1 or p2.

B = nthm_read (nthm_select (err), err);

Some points to note about this example are as follows.

• The first call to nthm_select blocks if neither of q1 or q2 is ready, regardless of p1 and p2 being ready or not.
• If there were more than two calls to nthm_select before nthm_exit_scope, the third and subsequent calls would return a NULL pipe despite the presence of p1 and p2.
• After the call to nthm_exit_scope, p1 and p2 are selectable as normal. Although one of q1 or q2 is still open, nthm_select ignores it.
• A scope once exited can not be re-entered. If another scope were entered in a continuation of this example, the remaining unread pipe assigned to q1 or q2 still would not be selectable in it.

The next example demonstrates multiple nested scopes.

a: nthm_enter_scope (err);       // outer scope

// Pipes opened here are selectable only here,
// between c: and d:, and between e: and f:.

b: nthm_enter_scope (err);       // nested scope

   // Pipes opened here are selectable nowhere else.

c: nthm_exit_scope (err);        // matches b:

// Pipes opened here are also selectable between
// e: and f:.

d: nthm_enter_scope (err);       // another nested scope

   // Pipes opened here are selectable nowhere else.

e: nthm_exit_scope (err);        // matches d:

// back in the outer scope

f: nthm_exit_scope (err);        // matches a:

NOTES

These functions can be helpful for library routines needing to operate on their own locally opened pipes while other pipes opened by the main application or other library routines continue in the background. A scope prevents the library routine from mistakenly selecting or interfering with pipes opened outside it.

If a routine runs in a separate thread from the main application, and that thread is created directly by pthreads primitives rather than as a side-effect of nthm_open, then all pipes it opens with nthm_open are automatically separate from those of the application without need of scopes.

SEE ALSO

nthm, nthm_open, nthm_send, nthm_select, nthm_truncate, nthm_truncate_all, nthm_truncated, 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