[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / 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>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="prev" href="module-select.html" />
	13	<link rel="parent" href="module-select.html" />
	14	<link rel="next" href="module-thread.html" />
	15	<meta name='aesop' content='information' />
	16	<title>7.3.1 Polling Objects </title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="7.3 select "
	24	href="module-select.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="7.3 select "
	27	href="module-select.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="7.4 thread "
	30	href="module-thread.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Python Library Reference</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	37	border='0' height='32' alt='Module Index' width='32' /></a></td>
	38	<td class='online-navigation'><a rel="index" title="Index"
	39	href="genindex.html"><img src='../icons/index.png'
	40	border='0' height='32' alt='Index' width='32' /></A></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="module-select.html">7.3 select </A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="module-select.html">7.3 select </A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="module-thread.html">7.4 thread </A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H2><A NAME="SECTION009310000000000000000"></A><A NAME="poll-objects"></A>
	55	<BR>
	56	7.3.1 Polling Objects
	57
	58	</H2>
	59
	60	<P>
	61	The <tt class="cfunction">poll()</tt> system call, supported on most <span class="Unix">Unix</span> systems,
	62	provides better scalability for network servers that service many,
	63	many clients at the same time.
	64	<tt class="cfunction">poll()</tt> scales better because the system call only
65	requires listing the file descriptors of interest, while <tt class="cfunction">select()</tt>
66	builds a bitmap, turns on bits for the fds of interest, and then
67	afterward the whole bitmap has to be linearly scanned again.
68	<tt class="cfunction">select()</tt> is O(highest file descriptor), while
69	<tt class="cfunction">poll()</tt> is O(number of file descriptors).
70
71	<P>
72	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
73	<td><nobr><b><tt id='l2h-2684' xml:id='l2h-2684' class="method">register</tt></b>(</nobr></td>
74	<td><var>fd</var><big>[</big><var>, eventmask</var><big>]</big><var></var>)</td></tr></table></dt>
75	<dd>
76	Register a file descriptor with the polling object. Future calls to
77	the <tt class="method">poll()</tt> method will then check whether the file descriptor
78	has any pending I/O events. <var>fd</var> can be either an integer, or an
79	object with a <tt class="method">fileno()</tt> method that returns an integer. File
80	objects implement
81	<tt class="method">fileno()</tt>, so they can also be used as the argument.
82
83	<P>
84	<var>eventmask</var> is an optional bitmask describing the type of events you
85	want to check for, and can be a combination of the constants
86	<tt class="constant">POLLIN</tt>, <tt class="constant">POLLPRI</tt>, and <tt class="constant">POLLOUT</tt>,
87	described in the table below. If not specified, the default value
88	used will check for all 3 types of events.
89
90	<P>
91	<div class="center"><table class="realtable">
92	<thead>
93	<tr>
94	<th class="left" >Constant</th>
95	<th class="left" >Meaning</th>
96	</tr>
97	</thead>
98	<tbody>
99	<tr><td class="left" valign="baseline"><tt class="constant">POLLIN</tt></td>
100	<td class="left" >There is data to read</td></tr>
101	<tr><td class="left" valign="baseline"><tt class="constant">POLLPRI</tt></td>
102	<td class="left" >There is urgent data to read</td></tr>
103	<tr><td class="left" valign="baseline"><tt class="constant">POLLOUT</tt></td>
104	<td class="left" >Ready for output: writing will not block</td></tr>
105	<tr><td class="left" valign="baseline"><tt class="constant">POLLERR</tt></td>
106	<td class="left" >Error condition of some sort</td></tr>
107	<tr><td class="left" valign="baseline"><tt class="constant">POLLHUP</tt></td>
108	<td class="left" >Hung up</td></tr>
109	<tr><td class="left" valign="baseline"><tt class="constant">POLLNVAL</tt></td>
110	<td class="left" >Invalid request: descriptor not open</td></tr></tbody>
111	</table></div>
112
113	<P>
114	Registering a file descriptor that's already registered is not an
115	error, and has the same effect as registering the descriptor exactly
116	once.
117	</dl>
118
119	<P>
120	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
121	<td><nobr><b><tt id='l2h-2685' xml:id='l2h-2685' class="method">unregister</tt></b>(</nobr></td>
122	<td><var>fd</var>)</td></tr></table></dt>
123	<dd>
124	Remove a file descriptor being tracked by a polling object. Just like
125	the <tt class="method">register()</tt> method, <var>fd</var> can be an integer or an
126	object with a <tt class="method">fileno()</tt> method that returns an integer.
127
128	<P>
129	Attempting to remove a file descriptor that was never registered
130	causes a <tt class="exception">KeyError</tt> exception to be raised.
131	</dl>
132
133	<P>
134	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
135	<td><nobr><b><tt id='l2h-2686' xml:id='l2h-2686' class="method">poll</tt></b>(</nobr></td>
136	<td><var></var><big>[</big><var>timeout</var><big>]</big><var></var>)</td></tr></table></dt>
137	<dd>
138	Polls the set of registered file descriptors, and returns a
139	possibly-empty list containing <code>(<var>fd</var>, <var>event</var>)</code> 2-tuples
140	for the descriptors that have events or errors to report.
141	<var>fd</var> is the file descriptor, and <var>event</var> is a bitmask
142	with bits set for the reported events for that descriptor
143	-- <tt class="constant">POLLIN</tt> for waiting input,
144	<tt class="constant">POLLOUT</tt> to indicate that the descriptor can be written to, and
145	so forth.
146	An empty list indicates that the call timed out and no file
147	descriptors had any events to report.
148	If <var>timeout</var> is given, it specifies the length of time in
149	milliseconds which the system will wait for events before returning.
150	If <var>timeout</var> is omitted, negative, or <tt class="constant">None</tt>, the call will
151	block until there is an event for this poll object.
152	</dl>
153
154	<DIV CLASS="navigation">
155	<div class='online-navigation'>
156	<p></p><hr />
157	<table align="center" width="100%" cellpadding="0" cellspacing="2">
158	<tr>
159	<td class='online-navigation'><a rel="prev" title="7.3 select "
160	href="module-select.html"><img src='../icons/previous.png'
161	border='0' height='32' alt='Previous Page' width='32' /></A></td>
162	<td class='online-navigation'><a rel="parent" title="7.3 select "
163	href="module-select.html"><img src='../icons/up.png'
164	border='0' height='32' alt='Up One Level' width='32' /></A></td>
165	<td class='online-navigation'><a rel="next" title="7.4 thread "
166	href="module-thread.html"><img src='../icons/next.png'
167	border='0' height='32' alt='Next Page' width='32' /></A></td>
168	<td align="center" width="100%">Python Library Reference</td>
169	<td class='online-navigation'><a rel="contents" title="Table of Contents"
170	href="contents.html"><img src='../icons/contents.png'
171	border='0' height='32' alt='Contents' width='32' /></A></td>
172	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
173	border='0' height='32' alt='Module Index' width='32' /></a></td>
174	<td class='online-navigation'><a rel="index" title="Index"
175	href="genindex.html"><img src='../icons/index.png'
176	border='0' height='32' alt='Index' width='32' /></A></td>
177	</tr></table>
178	<div class='online-navigation'>
179	<b class="navlabel">Previous:</b>
180	<a class="sectref" rel="prev" href="module-select.html">7.3 select </A>
181	<b class="navlabel">Up:</b>
182	<a class="sectref" rel="parent" href="module-select.html">7.3 select </A>
183	<b class="navlabel">Next:</b>
184	<a class="sectref" rel="next" href="module-thread.html">7.4 thread </A>
185	</div>
186	</div>
187	<hr />
188	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
189	</DIV>
190	<!--End of Navigation Panel-->
191	<ADDRESS>
192	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
193	</ADDRESS>
194	</BODY>
195	</HTML>