docs/nspr/nspr_poll_method.rst

   1 NSPR pool method
   2 ================
   3
   4 This technical note documents the poll method of PRFileDesc. The poll
   5 method is not to be confused with the PR_Poll function. The poll method
   6 operates on a single NetScape Portable Runtime (NSPR) file descriptor,
   7 whereas PR_Poll operates on a collection of NSPR file descriptors.
   8 PR_Poll uses the poll method behind the scene, but it is also possible
   9 to use the poll method directly.
  10
  11 We consider a stack of *NSPR I/O layers* on top of the *network
  12 transport*. Each I/O layer is represented by a PRFileDesc structure and
  13 the protocol of that layer is implemented by a PRIOMethods table. The
  14 bottom layer is a wrapper for the underlying network transport. The NSPR
  15 library provides a reference implementation of the bottom layer using
  16 the sockets API, but you can provide your own implementation of the
  17 bottom layer using another network transport API. The poll method is one
  18 of the functions in the PRIOMethods table. The prototype of the poll
  19 method is
  20
  21 .. code::
  22
  23    PRInt16 poll_method(PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags);
  24
  25 The purpose of the poll method is to allow a layer to modify that flags
  26 that will ultimately be used in the call to the underlying network
  27 transport's select (or equivalent) function, and to indicate that a
  28 layer is already able to make progress in the manner suggested by the
  29 polling flags. The arguments and return value of the poll method are
  30 described below.
  31
  32 .. _in_flags_input_argument:
  33
  34 in_flags [input argument]
  35 ~~~~~~~~~~~~~~~~~~~~~~~~~
  36
  37 The in_flags argument specifies the events at the **top layer** of the
  38 I/O layer stack that the caller is interested in.
  39
  40 -  For PR_Recv, you should pass PR_POLL_READ as the in_flags argument to
  41    the poll method
  42 -  For PR_Send, you should pass PR_POLL_WRITE as the in_flags argument
  43    to the poll method
  44
  45 .. _out_flags_output_argument:
  46
  47 out_flags [output argument]
  48 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  49
  50 If an I/O layer is ready to satisfy the I/O request defined by in_flags
  51 without involving the underlying network transport, its poll method sets
  52 the corresponding event in \*out_flags on return.
  53
  54 For example, consider an I/O layer that buffers input data. If the
  55 caller wishes to test for read ready (that is, PR_POLL_READ is set in
  56 in_flags) and the layer has input data buffered, the poll method would
  57 set the PR_POLL_READ event in \*out_flags. It can determine that without
  58 asking the underlying network transport.
  59
  60 The current implementation of PR_Poll (the primary user of the poll
  61 method) requires that the events in \*out_flags reflect the caller's
  62 view. This requirement may be relaxed in a future NSPR release. To
  63 remain compatible with this potential semantic change, NSPR clients
  64 should only use \*out_flags as described in the *How to use the poll
  65 method* section below.
  66
  67 .. _Return_value:
  68
  69 Return value
  70 ~~~~~~~~~~~~
  71
  72 If the poll method stores a nonzero value in \*out_flags, the return
  73 value will be the value of in_flags. (Note: this may change in a future
  74 NSPR release if we make the semantic change to \*out_flags mentioned
  75 above. Therefore, NSPR clients should only use the return value as
  76 described in *How to use the poll method* section below.) If the poll
  77 method stores zero in \*out_flags, the return value will be the bottom
  78 layer's desires with respect to the in_flags. Those are the events that
  79 the caller should poll the underlying network transport for. These
  80 events may be different from the events in in_flags (which reflect the
  81 caller's view) for some protocols.
  82
  83 .. _How_to_use_the_poll_method:
  84
  85 How to use the poll method
  86 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  87
  88 The poll method should only be used with a NSPR file descriptor in
  89 **non-blocking** mode. Most NSPR clients call PR_Poll and do not call
  90 the poll method directly. However, PR_Poll can only used with a stack
  91 whose bottom layer is NSPR's reference implementation. If you are using
  92 your own implementation of the bottom layer, you must call the poll
  93 method as follows.
  94
  95 Declare two PRInt16 variables to receive the return value and the
  96 out_flags output argument of the poll method.
  97
  98 .. code::
  99
 100    PRInt16 new_flags, out_flags;
 101
 102 If you are going to call PR_Recv, pass PR_POLL_READ as the in_flags
 103 argument.
 104
 105 .. code::
 106
 107    new_flags = fd->methods->poll(fd, PR_POLL_READ, &out_flags);
 108
 109 If you are going to call PR_Send, pass PR_POLL_WRITE as the in_flags
 110 argument.
 111
 112 .. code::
 113
 114    new_flags = fd->methods->poll(fd, PR_POLL_WRITE, &out_flags);
 115
 116 If you are interested in calling both PR_Recv and PR_Send on the same
 117 file descriptor, make two separate calls to the poll method, one with
 118 PR_POLL_READ as in_flags and the other with PR_POLL_WRITE as in_flags,
 119 so that you know what events at the network transport layer PR_POLL_READ
 120 and PR_POLL_WRITE are mapped to, respectively.
 121
 122 On return, if (new_flags & out_flags) is nonzero, you can try PR_Recv or
 123 PR_Send immediately.
 124
 125 Otherwise ((new_flags & out_flags) is 0), you should do the following.
 126
 127 -  If new_flags contains PR_POLL_READ, you should try PR_Recv or PR_Send
 128    when the underlying network transport is readable
 129 -  If new_flags contains PR_POLL_WRITE, you should try PR_Recv or
 130    PR_Send when the underlying network transport is writable
 131
 132 **Important** do not use out_flags in any way other than testing if
 133 (new_flags & out_flags) is 0. This is how PR_Poll (the primary user and
 134 hence the de facto specification of the poll method) uses out_flags.