NAME

       nbd_aio_get_direction - return the read or write direction

SYNOPSIS

        #include <libnbd.h>

        unsigned nbd_aio_get_direction (
                   struct nbd_handle *h
                 );

DESCRIPTION

       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

SEE ALSO

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

AUTHORS

       Eric Blake

       Richard W.M. Jones

COPYRIGHT

       Copyright Red Hat

LICENSE

       This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser
       General Public License as published by the Free Software Foundation; either version 2 of the License,  or
       (at your option) any later version.

       This  library  is  distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser  General
       Public License for more details.

       You should have received a copy of the GNU Lesser General Public License along with this library; if not,
       write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

libnbd-1.20.0                                      2024-04-05                           nbd_aio_get_direction(3)