1nbd_aio_get_direction(3)            LIBNBD            nbd_aio_get_direction(3)
2
3
4

NAME

6       nbd_aio_get_direction - return the read or write direction
7

SYNOPSIS

9        #include <libnbd.h>
10
11        unsigned nbd_aio_get_direction (
12                   struct nbd_handle *h
13                 );
14

DESCRIPTION

16       Return the current direction of this connection, which means whether we
17       are next expecting to read data from the server, write data to the
18       server, or both.  It returns
19
20       0   We are not expected to interact with the server file descriptor
21           from the current state. It is not worth attempting to use poll(2);
22           if the connection is not dead, then state machine progress must
23           instead come from some other means such as nbd_aio_connect(3).
24
25       "LIBNBD_AIO_DIRECTION_READ" = 1
26           We are expected next to read from the server.  If using poll(2) you
27           would set "events = POLLIN".  If "revents" returns "POLLIN" or
28           "POLLHUP" you would then call nbd_aio_notify_read(3).
29
30           Note that once libnbd reaches nbd_aio_is_ready(3), this direction
31           is returned even when there are no commands in flight (see
32           nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is
33           not worth polling until after issuing a command, as otherwise the
34           server will never wake up the poll. In a multi-threaded scenario,
35           you can have one thread begin a polling loop prior to any commands,
36           but any other thread that issues a command will need a way to kick
37           the polling thread out of poll in case issuing the command changes
38           the needed polling direction. Possible ways to do this include
39           polling for activity on a pipe-to-self, or using pthread_kill(3) to
40           send a signal that is masked except during ppoll(2).
41
42       "LIBNBD_AIO_DIRECTION_WRITE" = 2
43           We are expected next to write to the server.  If using poll(2) you
44           would set "events = POLLOUT".  If "revents" returns "POLLOUT" you
45           would then call nbd_aio_notify_write(3).
46
47       "LIBNBD_AIO_DIRECTION_BOTH" = 3
48           We are expected next to either read or write to the server.  If
49           using poll(2) you would set "events = POLLIN|POLLOUT".  If only one
50           of "POLLIN" or "POLLOUT" is returned, then see above.  However, if
51           both are returned, it is better to call only
52           nbd_aio_notify_read(3), as processing the server's reply may change
53           the state of the connection and invalidate the need to write more
54           commands.
55

RETURN VALUE

57       This call returns a bitmask.
58

ERRORS

60       This function does not fail.
61
62       The following parameters must not be NULL: "h".  For more information
63       see "Non-NULL parameters" in libnbd(3).
64

VERSION

66       This function first appeared in libnbd 1.0.
67
68       If you need to test if this function is available at compile time check
69       if the following macro is defined:
70
71        #define LIBNBD_HAVE_NBD_AIO_GET_DIRECTION 1
72

SEE ALSO

74       nbd_aio_connect(3), nbd_aio_in_flight(3), nbd_aio_is_ready(3),
75       nbd_aio_notify_read(3), nbd_aio_notify_write(3), nbd_create(3),
76       libnbd(3), poll(2), ppoll(2), pthread_kill(3).
77

AUTHORS

79       Eric Blake
80
81       Richard W.M. Jones
82
84       Copyright Red Hat
85

LICENSE

87       This library is free software; you can redistribute it and/or modify it
88       under the terms of the GNU Lesser General Public License as published
89       by the Free Software Foundation; either version 2 of the License, or
90       (at your option) any later version.
91
92       This library is distributed in the hope that it will be useful, but
93       WITHOUT ANY WARRANTY; without even the implied warranty of
94       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
95       Lesser General Public License for more details.
96
97       You should have received a copy of the GNU Lesser General Public
98       License along with this library; if not, write to the Free Software
99       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
100       02110-1301 USA
101
102
103
104libnbd-1.16.5                     2023-09-26          nbd_aio_get_direction(3)
Impressum