NAL_SELECTOR_NEW

Section: distcache (2)
Updated: 2004.03.23
Index Return to Main Contents
 

NAME

NAL_SELECTOR_new, NAL_SELECTOR_free, NAL_SELECTOR_select - libnal selector functions  

SYNOPSIS

 #include <libnal/nal.h>



 NAL_SELECTOR *NAL_SELECTOR_new(void);
 void NAL_SELECTOR_free(NAL_SELECTOR *sel);
 int NAL_SELECTOR_select(NAL_SELECTOR *sel, unsigned long usec_timeout,
                         int use_timeout);
 

DESCRIPTION

NAL_SELECTOR_new() allocates and initialises a new NAL_SELECTOR object.

NAL_SELECTOR_free() destroys a NAL_SELECTOR object.

NAL_SELECTOR_select() blocks until the selector sel receives notification of network events for which it has registered interest. This function blocks indefinitely until receipt of a network event, interruption by the system, or if use_timeout is non-zero, then the function will break if more than usec_timeout microseconds have passed. See ``NOTES''.  

RETURN VALUES

NAL_SELECTOR_new() returns a valid NAL_SELECTOR object on success, NULL otherwise.

NAL_SELECTOR_free() has no return value.

NAL_SELECTOR_select() returns negative for an error, otherwise it returns the number of connections and/or listeners that the selector has detected have network events waiting (which can be zero).  

NOTES

The NAL_SELECTOR allows the caller to register NAL_CONNECTION and NAL_LISTENER objects for any events appropriate to them and then block execution with NAL_SELECTOR_select() until there are events that need processing. The exact semantics NAL_CONNECTION_add_to_selector() and NAL_LISTENER_add_to_selector() are documented in other manual pages, see ``NOTES''.

The behaviour of NAL_SELECTOR_select() is what one would normally expect from a system select(2) function. On error, the return value is negative. Otherwise the return value is the number of connection and/or listener objects that have network events waiting for them. A return value of zero is possible if the function breaks before any network events have arrived, eg. if use_timeout was specified, or if a unblocked signal arrived. In such cases, subsequent calls to NAL_CONNECTION_io() and NAL_LISTENER_accept() will trivially return without performing any actions as the selector has no events registered for processing. As such, if NAL_SELECTOR_select() returns zero, it is generally advised to add the connections and listeners back to the selector object and call NAL_SELECTOR_select() again.

As with other libnal functions, `errno' is not touched so that any errors in the system's underlying implementations can be investigated directly by the calling application.  

SEE ALSO

NAL_ADDRESS_new(2) - Functions for the NAL_ADDRESS type.

NAL_CONNECTION_new(2) - Functions for the NAL_CONNECTION type.

NAL_LISTENER_new(2) - Functions for the NAL_LISTENER type.

NAL_BUFFER_new(2) - Functions for the NAL_BUFFER type.

distcache(8) - Overview of the distcache architecture.

http://www.distcache.org/ - Distcache home page.  

AUTHOR

This toolkit was designed and implemented by Geoff Thorpe for Cryptographic Appliances Incorporated. Since the project was released into open source, it has a home page and a project environment where development, mailing lists, and releases are organised. For problems with the software or this man page please check for new releases at the project web-site below, mail the users mailing list described there, or contact the author at geoff@geoffthorpe.net.

Home Page: http://www.distcache.org