Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 99a3701

Browse files
akuchlingakuchling
committed
Documentation for poll() interface (SF patch #100852)
1 parent 3227cc8 commit 99a3701

1 file changed

Lines changed: 76 additions & 1 deletion

File tree

‎Doc/lib/libselect.tex‎

Lines changed: 76 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ \section{\module{select} ---
55
\modulesynopsis{Wait for I/O completion on multiple streams.}
66

77

8-
This module provides access to the function \cfunction{select()}
8+
This module provides access to the \cfunction{select()}
9+
and \cfunction{poll()} functions
910
available in most operating systems. Note that on Windows, it only
1011
works for sockets; on other operating systems, it also works for other
1112
file types (in particular, on \UNIX{}, it works on pipes). It cannot
@@ -21,6 +22,14 @@ \section{\module{select} ---
2122
\cfunction{perror()}.
2223
\end{excdesc}
2324

25+
\begin{funcdesc}{poll}{}
26+
(Not supported by all operating systems.) Returns a polling object,
27+
which supports registering and unregistering file descriptors, and
28+
then polling them for I/O events;
29+
see section~\ref{poll-objects} below for the methods supported by
30+
polling objects.
31+
\end{funcdesc}
32+
2433
\begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
2534
This is a straightforward interface to the \UNIX{} \cfunction{select()}
2635
system call. The first three arguments are lists of `waitable
@@ -52,3 +61,69 @@ \section{\module{select} ---
5261
appropriate \method{fileno()} method (that really returns a \UNIX{}
5362
file descriptor, not just a random integer).
5463
\end{funcdesc}
64+
65+
\subsection{Polling Objects
66+
\label{poll-objects}}
67+
68+
The \cfunction{poll()} system call, supported on most Unix systems,
69+
provides better scalability for network servers that service many,
70+
many clients at the same time.
71+
\cfunction{poll()} scales better because the system call only
72+
requires listing the file descriptors of interest, while \cfunction{select()}
73+
builds a bitmap, turns on bits for the fds of interest, and then
74+
afterward the whole bitmap has to be linearly scanned again.
75+
\cfunction{select()} is O(highest file descriptor), while
76+
\cfunction{poll()} is O(number of file descriptors).
77+
78+
\begin{methoddesc}{register}{fd\optional{, eventmask}}
79+
Register a file descriptor with the polling object. Future calls to
80+
the \method{poll()} method will then check whether the file descriptor
81+
has any pending I/O events. \var{fd} can be either an integer, or an
82+
object with a \method{fileno()} method that returns an integer. File
83+
objects implement
84+
\method{fileno()}, so they can also be used as the argument.
85+
86+
\var{eventmask} is an optional bitmask describing the type of events you
87+
want to check for, and can be a combination of the constants
88+
\constant{POLLIN}, \constant{POLLPRI}, and \constant{POLLOUT},
89+
described in the table below. If not specified, the default value
90+
used will check for all 3 types of events.
91+
92+
\begin{tableii}{l|l}{code}{Constant}{Meaning}
93+
\lineii{POLLIN}{There is data to read}
94+
\lineii{POLLPRI}{There is urgent data to read}
95+
\lineii{POLLOUT}{Ready for output: writing will not block}
96+
\lineii{POLLERR}{Error condition of some sort}
97+
\lineii{POLLHUP}{Hung up}
98+
\lineii{POLLNVAL}{Invalid request: descriptor not open}
99+
\end{tableii}
100+
101+
Registering a file descriptor that's already registered is not an
102+
error, and has the same effect as registering the descriptor exactly
103+
once.
104+
105+
\end{methoddesc}
106+
107+
\begin{methoddesc}{unregister}{fd}
108+
Remove a file descriptor being tracked by a polling object. Just like
109+
the \method{register()} method, \var{fd} can be an integer or an
110+
object with a \method{fileno()} method that returns an integer.
111+
112+
Attempting to remove a file descriptor that was never registered
113+
causes a \exception{KeyError} exception to be raised.
114+
\end{methoddesc}
115+
116+
\begin{methoddesc}{poll}{\optional{timeout}}
117+
Polls the set of registered file descriptors, and returns a
118+
possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples
119+
for the descriptors that have events or errors to report.
120+
\var{fd} is the file descriptor, and \var{event} is a bitmask
121+
with bits set for the reported events for that descriptor
122+
--- \constant{POLLIN} for waiting input,
123+
\constant{POLLOUT} to indicate that the descriptor can be written to, and
124+
so forth.
125+
An empty list indicates that the call timed out and no file
126+
descriptors had any events to report.
127+
\end{methoddesc}
128+
129+

0 commit comments

Comments
 (0)