PR_Poll

Detects when I/O is ready for a set of socket file descriptors.

Syntax

#include <prio.h>

PRInt32 PR_Poll(
  PRPollDesc *pds,
  PRIntn npds,
  PRIntervalTime timeout);

Parameters

The function has the following parameters:

pds

A pointer to the first element of an array of PRPollDesc structures.

npds

The number of elements in the pds array. If this parameter is zero, PR_Poll is equivalent to PR_Sleep with a timeout.

timeout

Amount of time the call will block waiting for I/O to become ready. If this time expires without any I/O becoming ready, PR_Poll returns zero.

Returns

The function returns one of these values:

  • If successful, the function returns a positive number indicating the number of PRPollDesc structures in pds that have events.

  • The value 0 indicates the function timed out.

  • The value -1 indicates the function failed. The reason for the failure can be obtained by calling PR_GetError.

Description

This function returns as soon as I/O is ready on one or more of the underlying socket objects. A count of the number of ready descriptors is returned unless a timeout occurs, in which case zero is returned.

The in_flags field of the PRPollDesc data structure should be set to the I/O events (readable, writable, exception, or some combination) that the caller is interested in. On successful return, the out_flags field of the PRPollDesc data structure is set to indicate what kind of I/O is ready on the respective descriptor. PR_Poll uses the out_flags fields as scratch variables during the call. If PR_Poll returns 0 or -1, the out_flags fields do not contain meaningful values and must not be used.

The PRPollDesc structure is defined as follows:

struct PRPollDesc {
  PRFileDesc* fd;
  PRInt16 in_flags;
  PRInt16 out_flags;
};

typedef struct PRPollDesc PRPollDesc;

The structure has the following fields:

fd

A pointer to a PRFileDesc object representing a socket or a pollable event. This field can be set to NULL to indicate to PR_Poll that this PRFileDesc object should be ignored.

Note

On Unix, the fd field can be set to a pointer to any PRFileDesc object, including one representing a file or a pipe. Cross-platform applications should only set the fd field to a pointer to a PRFileDesc object representing a socket or a pollable event because on Windows the select function can only be used with sockets.

in_flags

A bitwise OR of the following bit flags:

  • PR_POLL_READ: fd is readable.

  • PR_POLL_WRITE: fd is writable.

  • PR_POLL_EXCEPT: fd has an exception condition.

out_flags

A bitwise OR of the following bit flags:

  • PR_POLL_READ

  • PR_POLL_WRITE

  • PR_POLL_EXCEPT

  • PR_POLL_ERR: fd has an error.

  • PR_POLL_NVAL: fd is bad.

Note that the PR_POLL_ERR and PR_POLL_NVAL flags are used only in out_flags. The PR_POLL_ERR and PR_POLL_NVAL events are always reported by PR_Poll.