1NAL_SELECTOR_NEW(2)                distcache               NAL_SELECTOR_NEW(2)
2
3
4

NAME

6       NAL_SELECTOR_new, NAL_SELECTOR_free, NAL_SELECTOR_select - libnal
7       selector functions
8

SYNOPSIS

10        #include <libnal/nal.h>
11
12        NAL_SELECTOR *NAL_SELECTOR_new(void);
13        void NAL_SELECTOR_free(NAL_SELECTOR *sel);
14        int NAL_SELECTOR_select(NAL_SELECTOR *sel, unsigned long usec_timeout,
15                                int use_timeout);
16

DESCRIPTION

18       NAL_SELECTOR_new() allocates and initialises a new NAL_SELECTOR object.
19
20       NAL_SELECTOR_free() destroys a NAL_SELECTOR object.
21
22       NAL_SELECTOR_select() blocks until the selector sel receives notifica‐
23       tion of network events for which it has registered interest. This func‐
24       tion blocks indefinitely until receipt of a network event, interruption
25       by the system, or if use_timeout is non-zero, then the function will
26       break if more than usec_timeout microseconds have passed. See "NOTES".
27

RETURN VALUES

29       NAL_SELECTOR_new() returns a valid NAL_SELECTOR object on success, NULL
30       otherwise.
31
32       NAL_SELECTOR_free() has no return value.
33
34       NAL_SELECTOR_select() returns negative for an error, otherwise it
35       returns the number of connections and/or listeners that the selector
36       has detected have network events waiting (which can be zero).
37

NOTES

39       The NAL_SELECTOR allows the caller to register NAL_CONNECTION and
40       NAL_LISTENER objects for any events appropriate to them and then block
41       execution with NAL_SELECTOR_select() until there are events that need
42       processing. The exact semantics NAL_CONNECTION_add_to_selector() and
43       NAL_LISTENER_add_to_selector() are documented in other manual pages,
44       see "NOTES".
45
46       The behaviour of NAL_SELECTOR_select() is what one would normally
47       expect from a system select(2) function. On error, the return value is
48       negative. Otherwise the return value is the number of connection and/or
49       listener objects that have network events waiting for them. A return
50       value of zero is possible if the function breaks before any network
51       events have arrived, eg. if use_timeout was specified, or if a
52       unblocked signal arrived. In such cases, subsequent calls to NAL_CON‐
53       NECTION_io() and NAL_LISTENER_accept() will trivially return without
54       performing any actions as the selector has no events registered for
55       processing. As such, if NAL_SELECTOR_select() returns zero, it is gen‐
56       erally advised to add the connections and listeners back to the selec‐
57       tor object and call NAL_SELECTOR_select() again.
58
59       As with other libnal functions, `errno' is not touched so that any
60       errors in the system's underlying implementations can be investigated
61       directly by the calling application.
62

SEE ALSO

64       NAL_ADDRESS_new(2) - Functions for the NAL_ADDRESS type.
65
66       NAL_CONNECTION_new(2) - Functions for the NAL_CONNECTION type.
67
68       NAL_LISTENER_new(2) - Functions for the NAL_LISTENER type.
69
70       NAL_BUFFER_new(2) - Functions for the NAL_BUFFER type.
71
72       distcache(8) - Overview of the distcache architecture.
73
74       http://www.distcache.org/ - Distcache home page.
75

AUTHOR

77       This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
78       graphic Appliances Incorporated. Since the project was released into
79       open source, it has a home page and a project environment where devel‐
80       opment, mailing lists, and releases are organised. For problems with
81       the software or this man page please check for new releases at the
82       project web-site below, mail the users mailing list described there, or
83       contact the author at geoff@geoffthorpe.net.
84
85       Home Page: http://www.distcache.org
86
87
88
891.4.5                             2004.03.23               NAL_SELECTOR_NEW(2)