docs/nspr/layeredpoll.rst

   1 PR_Poll() and the layered I/O
   2 =============================
   3
   4 *[last edited by AOF 8 August 1998]*
   5 This memo discusses some of the nuances of using PR_Poll() in
   6 conjunction with *layered I/O*. This is a relatively new feature in NSPR
   7 2.0, not that it hasn't been in the source tree for a while, but in that
   8 it has had no clients.
   9
  10 Implementation
  11 --------------
  12
  13 NSPR provides a public API function, PR_Poll() that is modeled after
  14 UNIX' ``poll()`` system call.
  15
  16 The implementation of :ref:`PR_Poll` is somewhat complicated. Not only
  17 does it map the :ref:`PRPollDesc` array into structures needed by the
  18 underlying OS, it also must deal with layered I/O. This is done despite
  19 the fact that :ref:`PR_Poll` itself is *not* layered. For every element
  20 of the :ref:`PRPollDesc` array that has a non-NULL :ref:`PRFileDesc` and whose
  21 ``in_flags`` are not zero, it calls the file descriptor's
  22 ``poll() method``.
  23 The ``poll()`` method is one of the vector contained in the
  24 :ref:`PRIOMethods` table. In the case of layered I/O, the elements (the
  25 methods) of the methods table may be overridden by the implementer of
  26 that layer. The layers are then *stacked.* I/O using that *stack* will
  27 call through the method at the top layer, and each layer may make
  28 altering decisions regarding how the I/O operation should proceed.
  29
  30 The purpose of the ``poll()`` method is to allow a layer to modify the
  31 flags that will ultimately be used in the call to the underlying OS'
  32 ``poll()`` (or equivalent) function. Such modification might be useful
  33 if one was implementing an augmented stream protocol (*e.g.,* **SSL**).
  34 SSL stands for **Secure Socket Layer**, hence the obvious applicability
  35 as an example. But it is way to complicated to describe in this memo, so
  36 this memo will use a much simpler layered protocol.
  37 The example protocol is one that, in order to send *n* bytes, it must
  38 first ask the connection's peer if the peer is willing to receive that
  39 many bytes. The form of the request is 4 bytes (binary) stating the
  40 number of bytes the sender wishes to transmit. The peer will send back
  41 the number of bytes it is willing to receive (in the test code there are
  42 no error conditions, so don't even ask).
  43
  44 The implication of the protocol is obvious. In order to do a
  45 :ref:`PR_Send` operation, the layer must first do a *different* send and
  46 then *receive* a response. Doing this and keeping the *stack's* client
  47 unaware is the goal. **It is not a goal of NSPR 2.0 to hide the nuances
  48 of synchronous verses non-blocking I/O**.
  49
  50 The layered methods
  51 -------------------
  52
  53 Each layer must implement a suitable function for *every* element of the
  54 methods table. One can get a copy of default methods by calling
  55 :ref:`PR_GetDefaultIOMethods` These methods simply pass all calls
  56 through the layer on to the next lower layer of the stack.
  57
  58 A layer implementer might copy the elements of the ``PRIOMethods``
  59 acquired from this function into a methods table of its own, then
  60 override just those methods of interest. *Usually* (with only a single
  61 exception) a layered method will perform its design duties and then call
  62 the next lower layer's equivalent function.
  63
  64 Layered ``poll()``
  65 ------------------
  66
  67 One of the more interesting methods is the ``poll()``. It is called by
  68 the runtime whenever the client calls :ref:`PR_Poll`. It may be called at
  69 the *top* layer for *every* file descriptor in the poll descriptor. It
  70 may be called zero or more times. The purpose of the ``poll()`` method
  71 is to provide the layer an opportunity to adjust the polling bits as
  72 needed. For instance, if a client (*i.e.*, top layer) is calling
  73 :ref:`PR_Poll` for a particular file descriptor with a *read* poll
  74 request, a lower layer might decide that it must perform a *write*
  75 first.
  76 In that case, the layer's ``poll()`` method would be called with
  77 **``in_flags``** including a ``PR_POLL_READ`` flag. However, the
  78 ``poll()`` method would call the next lower layer's ``poll()`` method
  79 with a ``PR_POLL_WRITE`` bit set. This process of re-assigning the poll
  80 flags can happen as many times as there are layers in the stack. It is
  81 the final value, the one returned to the caller of the top layer's
  82 ``poll()`` method (:ref:`PR_Poll`) that will be used by the runtime when
  83 calling the OS' ``poll()`` (or equivalent) system call.
  84
  85 It is expected that the modification of the polling bits propagate from
  86 the top of the stack down, allowing the layer closest to the bottom of
  87 the stack to provide the final setting. The implication is that there
  88 should be no modifications of the **``in_flags``** during the *return*
  89 phase of the layered function.
  90
  91 For example:
  92
  93 It is not advised to modify the ``final_in_flags`` between the call to
  94 the lower layer's ``poll()`` method and the ``return`` statement.
  95 The third argument of the ``poll()`` method is a pointer to a 16-bit
  96 word. If the layer sets a value in memory through that pointer *and*
  97 returns with a value that has *corresponding* bits, the runtime assumes
  98 that the file descriptor is ready immediately.
  99
 100 There are two important deviations from the normal. First, this is the
 101 one (known) exception to having a layered routine call the stack's next
 102 lower layer method. If bits are set in the ``out_flags`` the method
 103 should return *directly*. Second, the runtime will observe that the
 104 layer claims this file descriptor is ready and suppress the call to the
 105 OS' ``poll()`` system call.
 106
 107 At this time the only known use for this feature is to allow a layer to
 108 indicate it has buffered *input*. Note that it is not appropriate for
 109 buffered *output* since in order to write/send output the runtime must
 110 still confirm with the OS that such an operation is permitted.
 111
 112 Since the ``poll()`` method may be called zero or more times it must
 113 therefore be *idempotent* or at least *functional*. It will need to look
 114 at the layer's state, but must not make modifications to that state that
 115 would cause subsequent calls within the same :ref:`PR_Poll` call to
 116 return a different answer. Since the ``poll()`` method may not be called
 117 at all, so there is not guarantee that any modifications that would have
 118 been performed by the routine will every happen.