PR_Poll() and the layered I/O ============================= *[last edited by AOF 8 August 1998]* This memo discusses some of the nuances of using PR_Poll() in conjunction with *layered I/O*. This is a relatively new feature in NSPR 2.0, not that it hasn't been in the source tree for a while, but in that it has had no clients. Implementation -------------- NSPR provides a public API function, PR_Poll() that is modeled after UNIX' ``poll()`` system call. The implementation of :ref:`PR_Poll` is somewhat complicated. Not only does it map the :ref:`PRPollDesc` array into structures needed by the underlying OS, it also must deal with layered I/O. This is done despite the fact that :ref:`PR_Poll` itself is *not* layered. For every element of the :ref:`PRPollDesc` array that has a non-NULL :ref:`PRFileDesc` and whose ``in_flags`` are not zero, it calls the file descriptor's ``poll() method``. The ``poll()`` method is one of the vector contained in the :ref:`PRIOMethods` table. In the case of layered I/O, the elements (the methods) of the methods table may be overridden by the implementer of that layer. The layers are then *stacked.* I/O using that *stack* will call through the method at the top layer, and each layer may make altering decisions regarding how the I/O operation should proceed. The purpose of the ``poll()`` method is to allow a layer to modify the flags that will ultimately be used in the call to the underlying OS' ``poll()`` (or equivalent) function. Such modification might be useful if one was implementing an augmented stream protocol (*e.g.,* **SSL**). SSL stands for **Secure Socket Layer**, hence the obvious applicability as an example. But it is way to complicated to describe in this memo, so this memo will use a much simpler layered protocol. The example protocol is one that, in order to send *n* bytes, it must first ask the connection's peer if the peer is willing to receive that many bytes. The form of the request is 4 bytes (binary) stating the number of bytes the sender wishes to transmit. The peer will send back the number of bytes it is willing to receive (in the test code there are no error conditions, so don't even ask). The implication of the protocol is obvious. In order to do a :ref:`PR_Send` operation, the layer must first do a *different* send and then *receive* a response. Doing this and keeping the *stack's* client unaware is the goal. **It is not a goal of NSPR 2.0 to hide the nuances of synchronous verses non-blocking I/O**. The layered methods ------------------- Each layer must implement a suitable function for *every* element of the methods table. One can get a copy of default methods by calling :ref:`PR_GetDefaultIOMethods` These methods simply pass all calls through the layer on to the next lower layer of the stack. A layer implementer might copy the elements of the ``PRIOMethods`` acquired from this function into a methods table of its own, then override just those methods of interest. *Usually* (with only a single exception) a layered method will perform its design duties and then call the next lower layer's equivalent function. Layered ``poll()`` ------------------ One of the more interesting methods is the ``poll()``. It is called by the runtime whenever the client calls :ref:`PR_Poll`. It may be called at the *top* layer for *every* file descriptor in the poll descriptor. It may be called zero or more times. The purpose of the ``poll()`` method is to provide the layer an opportunity to adjust the polling bits as needed. For instance, if a client (*i.e.*, top layer) is calling :ref:`PR_Poll` for a particular file descriptor with a *read* poll request, a lower layer might decide that it must perform a *write* first. In that case, the layer's ``poll()`` method would be called with **``in_flags``** including a ``PR_POLL_READ`` flag. However, the ``poll()`` method would call the next lower layer's ``poll()`` method with a ``PR_POLL_WRITE`` bit set. This process of re-assigning the poll flags can happen as many times as there are layers in the stack. It is the final value, the one returned to the caller of the top layer's ``poll()`` method (:ref:`PR_Poll`) that will be used by the runtime when calling the OS' ``poll()`` (or equivalent) system call. It is expected that the modification of the polling bits propagate from the top of the stack down, allowing the layer closest to the bottom of the stack to provide the final setting. The implication is that there should be no modifications of the **``in_flags``** during the *return* phase of the layered function. For example: It is not advised to modify the ``final_in_flags`` between the call to the lower layer's ``poll()`` method and the ``return`` statement. The third argument of the ``poll()`` method is a pointer to a 16-bit word. If the layer sets a value in memory through that pointer *and* returns with a value that has *corresponding* bits, the runtime assumes that the file descriptor is ready immediately. There are two important deviations from the normal. First, this is the one (known) exception to having a layered routine call the stack's next lower layer method. If bits are set in the ``out_flags`` the method should return *directly*. Second, the runtime will observe that the layer claims this file descriptor is ready and suppress the call to the OS' ``poll()`` system call. At this time the only known use for this feature is to allow a layer to indicate it has buffered *input*. Note that it is not appropriate for buffered *output* since in order to write/send output the runtime must still confirm with the OS that such an operation is permitted. Since the ``poll()`` method may be called zero or more times it must therefore be *idempotent* or at least *functional*. It will need to look at the layer's state, but must not make modifications to that state that would cause subsequent calls within the same :ref:`PR_Poll` call to return a different answer. Since the ``poll()`` method may not be called at all, so there is not guarantee that any modifications that would have been performed by the routine will every happen.