nbd_aio_get_direction3

Usage

 #include <libnbd.h>
 unsigned nbd_aio_get_direction (
            struct nbd_handle *h
          );

Overview

Return the current direction of this connection, which means whether we are next expecting to read data from the server, write data to the server, or both. It returns

0

We are not expected to interact with the server file descriptor from the current state. It is not worth attempting to use poll(2); if the connection is not dead, then state machine progress must instead come from some other means such as nbd_aio_connect(3).

"LIBNBD_AIO_DIRECTION_READ" = 1

We are expected next to read from the server. If using poll(2) you would set "events = POLLIN". If "revents" returns "POLLIN" or "POLLHUP" you would then call nbd_aio_notify_read(3).

Note that once libnbd reaches nbd_aio_is_ready(3), this direction is returned even when there are no commands in flight (see nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is not worth polling until after issuing a command, as otherwise the server will never wake up the poll. In a multi-threaded scenario, you can have one thread begin a polling loop prior to any commands, but any other thread that issues a command will need a way to kick the polling thread out of poll in case issuing the command changes the needed polling direction. Possible ways to do this include polling for activity on a pipe-to-self, or using pthread_kill(3) to send a signal that is masked except during ppoll(2).

"LIBNBD_AIO_DIRECTION_WRITE" = 2

We are expected next to write to the server. If using poll(2) you would set "events = POLLOUT". If "revents" returns "POLLOUT" you would then call nbd_aio_notify_write(3).

"LIBNBD_AIO_DIRECTION_BOTH" = 3

We are expected next to either read or write to the server. If using poll(2) you would set "events = POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then see above. However, if both are returned, it is better to call only nbd_aio_notify_read(3), as processing the server's reply may change the state of the connection and invalidate the need to write more commands.

Return value

This call returns a bitmask.

Errors

This function does not fail.

The following parameters must not be NULL: "h". For more information see "Non-NULL parameters" in libnbd(3).

Version

This function first appeared in libnbd 1.0.

If you need to test if this function is available at compile time check if the following macro is defined:

 #define LIBNBD_HAVE_NBD_AIO_GET_DIRECTION 1