tools/src/nas,5.n2.os.2/lib/python/html/python/lib/poll-objects.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="module-select.html" />
<link rel="parent" href="module-select.html" />
<link rel="next" href="module-thread.html" />
<meta name='aesop' content='information' />
<title>7.3.1 Polling Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.3 select  "
  href="module-select.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.3 select  "
  href="module-select.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.4 thread  "
  href="module-thread.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-select.html">7.3 select  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-select.html">7.3 select  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-thread.html">7.4 thread  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION009310000000000000000"></A><A NAME="poll-objects"></A>
<BR>
7.3.1 Polling Objects

</H2>

<P>
The <tt class="cfunction">poll()</tt> system call, supported on most <span class="Unix">Unix</span> systems,
provides better scalability for network servers that service many,
many clients at the same time.
<tt class="cfunction">poll()</tt> scales better because the system call only
requires listing the file descriptors of interest, while <tt class="cfunction">select()</tt>
builds a bitmap, turns on bits for the fds of interest, and then
afterward the whole bitmap has to be linearly scanned again.
<tt class="cfunction">select()</tt> is O(highest file descriptor), while
<tt class="cfunction">poll()</tt> is O(number of file descriptors).

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2684' xml:id='l2h-2684' class="method">register</tt></b>(</nobr></td>
  <td><var>fd</var><big>[</big><var>, eventmask</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Register a file descriptor with the polling object.  Future calls to
the <tt class="method">poll()</tt> method will then check whether the file descriptor
has any pending I/O events.  <var>fd</var> can be either an integer, or an
object with a <tt class="method">fileno()</tt> method that returns an integer.  File
objects implement
<tt class="method">fileno()</tt>, so they can also be used as the argument.

<P>
<var>eventmask</var> is an optional bitmask describing the type of events you
want to check for, and can be a combination of the constants
<tt class="constant">POLLIN</tt>, <tt class="constant">POLLPRI</tt>, and <tt class="constant">POLLOUT</tt>,
described in the table below.  If not specified, the default value
used will check for all 3 types of events.

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Constant</th>
      <th class="left"  >Meaning</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline"><tt class="constant">POLLIN</tt></td>
        <td class="left"  >There is data to read</td></tr>
    <tr><td class="left"   valign="baseline"><tt class="constant">POLLPRI</tt></td>
        <td class="left"  >There is urgent data to read</td></tr>
    <tr><td class="left"   valign="baseline"><tt class="constant">POLLOUT</tt></td>
        <td class="left"  >Ready for output: writing will not block</td></tr>
    <tr><td class="left"   valign="baseline"><tt class="constant">POLLERR</tt></td>
        <td class="left"  >Error condition of some sort</td></tr>
    <tr><td class="left"   valign="baseline"><tt class="constant">POLLHUP</tt></td>
        <td class="left"  >Hung up</td></tr>
    <tr><td class="left"   valign="baseline"><tt class="constant">POLLNVAL</tt></td>
        <td class="left"  >Invalid request: descriptor not open</td></tr></tbody>
</table></div>

<P>
Registering a file descriptor that's already registered is not an
error, and has the same effect as registering the descriptor exactly
once.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2685' xml:id='l2h-2685' class="method">unregister</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Remove a file descriptor being tracked by a polling object.  Just like
the <tt class="method">register()</tt> method, <var>fd</var> can be an integer or an
object with a <tt class="method">fileno()</tt> method that returns an integer.

<P>
Attempting to remove a file descriptor that was never registered
causes a <tt class="exception">KeyError</tt> exception to be raised.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2686' xml:id='l2h-2686' class="method">poll</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>timeout</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Polls the set of registered file descriptors, and returns a
possibly-empty list containing <code>(<var>fd</var>, <var>event</var>)</code> 2-tuples
for the descriptors that have events or errors to report.
<var>fd</var> is the file descriptor, and <var>event</var> is a bitmask
with bits set for the reported events for that descriptor
-- <tt class="constant">POLLIN</tt> for waiting input,
<tt class="constant">POLLOUT</tt> to indicate that the descriptor can be written to, and
so forth.
An empty list indicates that the call timed out and no file
descriptors had any events to report.
If <var>timeout</var> is given, it specifies the length of time in
milliseconds which the system will wait for events before returning.
If <var>timeout</var> is omitted, negative, or <tt class="constant">None</tt>, the call will
block until there is an event for this poll object.
</dl>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.3 select  "
  href="module-select.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.3 select  "
  href="module-select.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.4 thread  "
  href="module-thread.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-select.html">7.3 select  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-select.html">7.3 select  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-thread.html">7.4 thread  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>