gecko-dev/docs/nspr/nspr_poll_method.rst

NSPR pool method
================

This technical note documents the poll method of PRFileDesc. The poll
method is not to be confused with the PR_Poll function. The poll method
operates on a single NetScape Portable Runtime (NSPR) file descriptor,
whereas PR_Poll operates on a collection of NSPR file descriptors.
PR_Poll uses the poll method behind the scene, but it is also possible
to use the poll method directly.

We consider a stack of *NSPR I/O layers* on top of the *network
transport*. Each I/O layer is represented by a PRFileDesc structure and
the protocol of that layer is implemented by a PRIOMethods table. The
bottom layer is a wrapper for the underlying network transport. The NSPR
library provides a reference implementation of the bottom layer using
the sockets API, but you can provide your own implementation of the
bottom layer using another network transport API. The poll method is one
of the functions in the PRIOMethods table. The prototype of the poll
method is

.. code::

   PRInt16 poll_method(PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags);

The purpose of the poll method is to allow a layer to modify that flags
that will ultimately be used in the call to the underlying network
transport's select (or equivalent) function, and to indicate that a
layer is already able to make progress in the manner suggested by the
polling flags. The arguments and return value of the poll method are
described below.

.. _in_flags_input_argument:

in_flags [input argument]
~~~~~~~~~~~~~~~~~~~~~~~~~

The in_flags argument specifies the events at the **top layer** of the
I/O layer stack that the caller is interested in.

-  For PR_Recv, you should pass PR_POLL_READ as the in_flags argument to
   the poll method
-  For PR_Send, you should pass PR_POLL_WRITE as the in_flags argument
   to the poll method

.. _out_flags_output_argument:

out_flags [output argument]
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If an I/O layer is ready to satisfy the I/O request defined by in_flags
without involving the underlying network transport, its poll method sets
the corresponding event in \*out_flags on return.

For example, consider an I/O layer that buffers input data. If the
caller wishes to test for read ready (that is, PR_POLL_READ is set in
in_flags) and the layer has input data buffered, the poll method would
set the PR_POLL_READ event in \*out_flags. It can determine that without
asking the underlying network transport.

The current implementation of PR_Poll (the primary user of the poll
method) requires that the events in \*out_flags reflect the caller's
view. This requirement may be relaxed in a future NSPR release. To
remain compatible with this potential semantic change, NSPR clients
should only use \*out_flags as described in the *How to use the poll
method* section below.

.. _Return_value:

Return value
~~~~~~~~~~~~

If the poll method stores a nonzero value in \*out_flags, the return
value will be the value of in_flags. (Note: this may change in a future
NSPR release if we make the semantic change to \*out_flags mentioned
above. Therefore, NSPR clients should only use the return value as
described in *How to use the poll method* section below.) If the poll
method stores zero in \*out_flags, the return value will be the bottom
layer's desires with respect to the in_flags. Those are the events that
the caller should poll the underlying network transport for. These
events may be different from the events in in_flags (which reflect the
caller's view) for some protocols.

.. _How_to_use_the_poll_method:

How to use the poll method
~~~~~~~~~~~~~~~~~~~~~~~~~~

The poll method should only be used with a NSPR file descriptor in
**non-blocking** mode. Most NSPR clients call PR_Poll and do not call
the poll method directly. However, PR_Poll can only used with a stack
whose bottom layer is NSPR's reference implementation. If you are using
your own implementation of the bottom layer, you must call the poll
method as follows.

Declare two PRInt16 variables to receive the return value and the
out_flags output argument of the poll method.

.. code::

   PRInt16 new_flags, out_flags;

If you are going to call PR_Recv, pass PR_POLL_READ as the in_flags
argument.

.. code::

   new_flags = fd->methods->poll(fd, PR_POLL_READ, &out_flags);

If you are going to call PR_Send, pass PR_POLL_WRITE as the in_flags
argument.

.. code::

   new_flags = fd->methods->poll(fd, PR_POLL_WRITE, &out_flags);

If you are interested in calling both PR_Recv and PR_Send on the same
file descriptor, make two separate calls to the poll method, one with
PR_POLL_READ as in_flags and the other with PR_POLL_WRITE as in_flags,
so that you know what events at the network transport layer PR_POLL_READ
and PR_POLL_WRITE are mapped to, respectively.

On return, if (new_flags & out_flags) is nonzero, you can try PR_Recv or
PR_Send immediately.

Otherwise ((new_flags & out_flags) is 0), you should do the following.

-  If new_flags contains PR_POLL_READ, you should try PR_Recv or PR_Send
   when the underlying network transport is readable
-  If new_flags contains PR_POLL_WRITE, you should try PR_Recv or
   PR_Send when the underlying network transport is writable

**Important** do not use out_flags in any way other than testing if
(new_flags & out_flags) is 0. This is how PR_Poll (the primary user and
hence the de facto specification of the poll method) uses out_flags.