Python code coverage for Lib/selectors.py

#	count	content
1	n/a	"""Selectors module.
2	n/a
3	n/a	This module allows high-level and efficient I/O multiplexing, built upon the
4	n/a	`select` module primitives.
5	n/a	"""
6	n/a
7	n/a
8	n/a	from abc import ABCMeta, abstractmethod
9	n/a	from collections import namedtuple, Mapping
10	n/a	import math
11	n/a	import select
12	n/a	import sys
13	n/a
14	n/a
15	n/a	# generic events, that must be mapped to implementation-specific ones
16	n/a	EVENT_READ = (1 << 0)
17	n/a	EVENT_WRITE = (1 << 1)
18	n/a
19	n/a
20	n/a	def _fileobj_to_fd(fileobj):
21	n/a	"""Return a file descriptor from a file object.
22	n/a
23	n/a	Parameters:
24	n/a	fileobj -- file object or file descriptor
25	n/a
26	n/a	Returns:
27	n/a	corresponding file descriptor
28	n/a
29	n/a	Raises:
30	n/a	ValueError if the object is invalid
31	n/a	"""
32	n/a	if isinstance(fileobj, int):
33	n/a	fd = fileobj
34	n/a	else:
35	n/a	try:
36	n/a	fd = int(fileobj.fileno())
37	n/a	except (AttributeError, TypeError, ValueError):
38	n/a	raise ValueError("Invalid file object: "
39	n/a	"{!r}".format(fileobj)) from None
40	n/a	if fd < 0:
41	n/a	raise ValueError("Invalid file descriptor: {}".format(fd))
42	n/a	return fd
43	n/a
44	n/a
45	n/a	SelectorKey = namedtuple('SelectorKey', ['fileobj', 'fd', 'events', 'data'])
46	n/a
47	n/a	SelectorKey.__doc__ = """SelectorKey(fileobj, fd, events, data)
48	n/a
49	n/a	Object used to associate a file object to its backing
50	n/a	file descriptor, selected event mask, and attached data.
51	n/a	"""
52	n/a	if sys.version_info >= (3, 5):
53	n/a	SelectorKey.fileobj.__doc__ = 'File object registered.'
54	n/a	SelectorKey.fd.__doc__ = 'Underlying file descriptor.'
55	n/a	SelectorKey.events.__doc__ = 'Events that must be waited for on this file object.'
56	n/a	SelectorKey.data.__doc__ = ('''Optional opaque data associated to this file object.
57	n/a	For example, this could be used to store a per-client session ID.''')
58	n/a
59	n/a	class _SelectorMapping(Mapping):
60	n/a	"""Mapping of file objects to selector keys."""
61	n/a
62	n/a	def __init__(self, selector):
63	n/a	self._selector = selector
64	n/a
65	n/a	def __len__(self):
66	n/a	return len(self._selector._fd_to_key)
67	n/a
68	n/a	def __getitem__(self, fileobj):
69	n/a	try:
70	n/a	fd = self._selector._fileobj_lookup(fileobj)
71	n/a	return self._selector._fd_to_key[fd]
72	n/a	except KeyError:
73	n/a	raise KeyError("{!r} is not registered".format(fileobj)) from None
74	n/a
75	n/a	def __iter__(self):
76	n/a	return iter(self._selector._fd_to_key)
77	n/a
78	n/a
79	n/a	class BaseSelector(metaclass=ABCMeta):
80	n/a	"""Selector abstract base class.
81	n/a
82	n/a	A selector supports registering file objects to be monitored for specific
83	n/a	I/O events.
84	n/a
85	n/a	A file object is a file descriptor or any object with a `fileno()` method.
86	n/a	An arbitrary object can be attached to the file object, which can be used
87	n/a	for example to store context information, a callback, etc.
88	n/a
89	n/a	A selector can use various implementations (select(), poll(), epoll()...)
90	n/a	depending on the platform. The default `Selector` class uses the most
91	n/a	efficient implementation on the current platform.
92	n/a	"""
93	n/a
94	n/a	@abstractmethod
95	n/a	def register(self, fileobj, events, data=None):
96	n/a	"""Register a file object.
97	n/a
98	n/a	Parameters:
99	n/a	fileobj -- file object or file descriptor
100	n/a	events -- events to monitor (bitwise mask of EVENT_READ\|EVENT_WRITE)
101	n/a	data -- attached data
102	n/a
103	n/a	Returns:
104	n/a	SelectorKey instance
105	n/a
106	n/a	Raises:
107	n/a	ValueError if events is invalid
108	n/a	KeyError if fileobj is already registered
109	n/a	OSError if fileobj is closed or otherwise is unacceptable to
110	n/a	the underlying system call (if a system call is made)
111	n/a
112	n/a	Note:
113	n/a	OSError may or may not be raised
114	n/a	"""
115	n/a	raise NotImplementedError
116	n/a
117	n/a	@abstractmethod
118	n/a	def unregister(self, fileobj):
119	n/a	"""Unregister a file object.
120	n/a
121	n/a	Parameters:
122	n/a	fileobj -- file object or file descriptor
123	n/a
124	n/a	Returns:
125	n/a	SelectorKey instance
126	n/a
127	n/a	Raises:
128	n/a	KeyError if fileobj is not registered
129	n/a
130	n/a	Note:
131	n/a	If fileobj is registered but has since been closed this does
132	n/a	not raise OSError (even if the wrapped syscall does)
133	n/a	"""
134	n/a	raise NotImplementedError
135	n/a
136	n/a	def modify(self, fileobj, events, data=None):
137	n/a	"""Change a registered file object monitored events or attached data.
138	n/a
139	n/a	Parameters:
140	n/a	fileobj -- file object or file descriptor
141	n/a	events -- events to monitor (bitwise mask of EVENT_READ\|EVENT_WRITE)
142	n/a	data -- attached data
143	n/a
144	n/a	Returns:
145	n/a	SelectorKey instance
146	n/a
147	n/a	Raises:
148	n/a	Anything that unregister() or register() raises
149	n/a	"""
150	n/a	self.unregister(fileobj)
151	n/a	return self.register(fileobj, events, data)
152	n/a
153	n/a	@abstractmethod
154	n/a	def select(self, timeout=None):
155	n/a	"""Perform the actual selection, until some monitored file objects are
156	n/a	ready or a timeout expires.
157	n/a
158	n/a	Parameters:
159	n/a	timeout -- if timeout > 0, this specifies the maximum wait time, in
160	n/a	seconds
161	n/a	if timeout <= 0, the select() call won't block, and will
162	n/a	report the currently ready file objects
163	n/a	if timeout is None, select() will block until a monitored
164	n/a	file object becomes ready
165	n/a
166	n/a	Returns:
167	n/a	list of (key, events) for ready file objects
168	n/a	`events` is a bitwise mask of EVENT_READ\|EVENT_WRITE
169	n/a	"""
170	n/a	raise NotImplementedError
171	n/a
172	n/a	def close(self):
173	n/a	"""Close the selector.
174	n/a
175	n/a	This must be called to make sure that any underlying resource is freed.
176	n/a	"""
177	n/a	pass
178	n/a
179	n/a	def get_key(self, fileobj):
180	n/a	"""Return the key associated to a registered file object.
181	n/a
182	n/a	Returns:
183	n/a	SelectorKey for this file object
184	n/a	"""
185	n/a	mapping = self.get_map()
186	n/a	if mapping is None:
187	n/a	raise RuntimeError('Selector is closed')
188	n/a	try:
189	n/a	return mapping[fileobj]
190	n/a	except KeyError:
191	n/a	raise KeyError("{!r} is not registered".format(fileobj)) from None
192	n/a
193	n/a	@abstractmethod
194	n/a	def get_map(self):
195	n/a	"""Return a mapping of file objects to selector keys."""
196	n/a	raise NotImplementedError
197	n/a
198	n/a	def __enter__(self):
199	n/a	return self
200	n/a
201	n/a	def __exit__(self, *args):
202	n/a	self.close()
203	n/a
204	n/a
205	n/a	class _BaseSelectorImpl(BaseSelector):
206	n/a	"""Base selector implementation."""
207	n/a
208	n/a	def __init__(self):
209	n/a	# this maps file descriptors to keys
210	n/a	self._fd_to_key = {}
211	n/a	# read-only mapping returned by get_map()
212	n/a	self._map = _SelectorMapping(self)
213	n/a
214	n/a	def _fileobj_lookup(self, fileobj):
215	n/a	"""Return a file descriptor from a file object.
216	n/a
217	n/a	This wraps _fileobj_to_fd() to do an exhaustive search in case
218	n/a	the object is invalid but we still have it in our map. This
219	n/a	is used by unregister() so we can unregister an object that
220	n/a	was previously registered even if it is closed. It is also
221	n/a	used by _SelectorMapping.
222	n/a	"""
223	n/a	try:
224	n/a	return _fileobj_to_fd(fileobj)
225	n/a	except ValueError:
226	n/a	# Do an exhaustive search.
227	n/a	for key in self._fd_to_key.values():
228	n/a	if key.fileobj is fileobj:
229	n/a	return key.fd
230	n/a	# Raise ValueError after all.
231	n/a	raise
232	n/a
233	n/a	def register(self, fileobj, events, data=None):
234	n/a	if (not events) or (events & ~(EVENT_READ \| EVENT_WRITE)):
235	n/a	raise ValueError("Invalid events: {!r}".format(events))
236	n/a
237	n/a	key = SelectorKey(fileobj, self._fileobj_lookup(fileobj), events, data)
238	n/a
239	n/a	if key.fd in self._fd_to_key:
240	n/a	raise KeyError("{!r} (FD {}) is already registered"
241	n/a	.format(fileobj, key.fd))
242	n/a
243	n/a	self._fd_to_key[key.fd] = key
244	n/a	return key
245	n/a
246	n/a	def unregister(self, fileobj):
247	n/a	try:
248	n/a	key = self._fd_to_key.pop(self._fileobj_lookup(fileobj))
249	n/a	except KeyError:
250	n/a	raise KeyError("{!r} is not registered".format(fileobj)) from None
251	n/a	return key
252	n/a
253	n/a	def modify(self, fileobj, events, data=None):
254	n/a	# TODO: Subclasses can probably optimize this even further.
255	n/a	try:
256	n/a	key = self._fd_to_key[self._fileobj_lookup(fileobj)]
257	n/a	except KeyError:
258	n/a	raise KeyError("{!r} is not registered".format(fileobj)) from None
259	n/a	if events != key.events:
260	n/a	self.unregister(fileobj)
261	n/a	key = self.register(fileobj, events, data)
262	n/a	elif data != key.data:
263	n/a	# Use a shortcut to update the data.
264	n/a	key = key._replace(data=data)
265	n/a	self._fd_to_key[key.fd] = key
266	n/a	return key
267	n/a
268	n/a	def close(self):
269	n/a	self._fd_to_key.clear()
270	n/a	self._map = None
271	n/a
272	n/a	def get_map(self):
273	n/a	return self._map
274	n/a
275	n/a	def _key_from_fd(self, fd):
276	n/a	"""Return the key associated to a given file descriptor.
277	n/a
278	n/a	Parameters:
279	n/a	fd -- file descriptor
280	n/a
281	n/a	Returns:
282	n/a	corresponding key, or None if not found
283	n/a	"""
284	n/a	try:
285	n/a	return self._fd_to_key[fd]
286	n/a	except KeyError:
287	n/a	return None
288	n/a
289	n/a
290	n/a	class SelectSelector(_BaseSelectorImpl):
291	n/a	"""Select-based selector."""
292	n/a
293	n/a	def __init__(self):
294	n/a	super().__init__()
295	n/a	self._readers = set()
296	n/a	self._writers = set()
297	n/a
298	n/a	def register(self, fileobj, events, data=None):
299	n/a	key = super().register(fileobj, events, data)
300	n/a	if events & EVENT_READ:
301	n/a	self._readers.add(key.fd)
302	n/a	if events & EVENT_WRITE:
303	n/a	self._writers.add(key.fd)
304	n/a	return key
305	n/a
306	n/a	def unregister(self, fileobj):
307	n/a	key = super().unregister(fileobj)
308	n/a	self._readers.discard(key.fd)
309	n/a	self._writers.discard(key.fd)
310	n/a	return key
311	n/a
312	n/a	if sys.platform == 'win32':
313	n/a	def _select(self, r, w, _, timeout=None):
314	n/a	r, w, x = select.select(r, w, w, timeout)
315	n/a	return r, w + x, []
316	n/a	else:
317	n/a	_select = select.select
318	n/a
319	n/a	def select(self, timeout=None):
320	n/a	timeout = None if timeout is None else max(timeout, 0)
321	n/a	ready = []
322	n/a	try:
323	n/a	r, w, _ = self._select(self._readers, self._writers, [], timeout)
324	n/a	except InterruptedError:
325	n/a	return ready
326	n/a	r = set(r)
327	n/a	w = set(w)
328	n/a	for fd in r \| w:
329	n/a	events = 0
330	n/a	if fd in r:
331	n/a	events \|= EVENT_READ
332	n/a	if fd in w:
333	n/a	events \|= EVENT_WRITE
334	n/a
335	n/a	key = self._key_from_fd(fd)
336	n/a	if key:
337	n/a	ready.append((key, events & key.events))
338	n/a	return ready
339	n/a
340	n/a
341	n/a	if hasattr(select, 'poll'):
342	n/a
343	n/a	class PollSelector(_BaseSelectorImpl):
344	n/a	"""Poll-based selector."""
345	n/a
346	n/a	def __init__(self):
347	n/a	super().__init__()
348	n/a	self._poll = select.poll()
349	n/a
350	n/a	def register(self, fileobj, events, data=None):
351	n/a	key = super().register(fileobj, events, data)
352	n/a	poll_events = 0
353	n/a	if events & EVENT_READ:
354	n/a	poll_events \|= select.POLLIN
355	n/a	if events & EVENT_WRITE:
356	n/a	poll_events \|= select.POLLOUT
357	n/a	self._poll.register(key.fd, poll_events)
358	n/a	return key
359	n/a
360	n/a	def unregister(self, fileobj):
361	n/a	key = super().unregister(fileobj)
362	n/a	self._poll.unregister(key.fd)
363	n/a	return key
364	n/a
365	n/a	def select(self, timeout=None):
366	n/a	if timeout is None:
367	n/a	timeout = None
368	n/a	elif timeout <= 0:
369	n/a	timeout = 0
370	n/a	else:
371	n/a	# poll() has a resolution of 1 millisecond, round away from
372	n/a	# zero to wait at least timeout seconds.
373	n/a	timeout = math.ceil(timeout * 1e3)
374	n/a	ready = []
375	n/a	try:
376	n/a	fd_event_list = self._poll.poll(timeout)
377	n/a	except InterruptedError:
378	n/a	return ready
379	n/a	for fd, event in fd_event_list:
380	n/a	events = 0
381	n/a	if event & ~select.POLLIN:
382	n/a	events \|= EVENT_WRITE
383	n/a	if event & ~select.POLLOUT:
384	n/a	events \|= EVENT_READ
385	n/a
386	n/a	key = self._key_from_fd(fd)
387	n/a	if key:
388	n/a	ready.append((key, events & key.events))
389	n/a	return ready
390	n/a
391	n/a
392	n/a	if hasattr(select, 'epoll'):
393	n/a
394	n/a	class EpollSelector(_BaseSelectorImpl):
395	n/a	"""Epoll-based selector."""
396	n/a
397	n/a	def __init__(self):
398	n/a	super().__init__()
399	n/a	self._epoll = select.epoll()
400	n/a
401	n/a	def fileno(self):
402	n/a	return self._epoll.fileno()
403	n/a
404	n/a	def register(self, fileobj, events, data=None):
405	n/a	key = super().register(fileobj, events, data)
406	n/a	epoll_events = 0
407	n/a	if events & EVENT_READ:
408	n/a	epoll_events \|= select.EPOLLIN
409	n/a	if events & EVENT_WRITE:
410	n/a	epoll_events \|= select.EPOLLOUT
411	n/a	try:
412	n/a	self._epoll.register(key.fd, epoll_events)
413	n/a	except BaseException:
414	n/a	super().unregister(fileobj)
415	n/a	raise
416	n/a	return key
417	n/a
418	n/a	def unregister(self, fileobj):
419	n/a	key = super().unregister(fileobj)
420	n/a	try:
421	n/a	self._epoll.unregister(key.fd)
422	n/a	except OSError:
423	n/a	# This can happen if the FD was closed since it
424	n/a	# was registered.
425	n/a	pass
426	n/a	return key
427	n/a
428	n/a	def select(self, timeout=None):
429	n/a	if timeout is None:
430	n/a	timeout = -1
431	n/a	elif timeout <= 0:
432	n/a	timeout = 0
433	n/a	else:
434	n/a	# epoll_wait() has a resolution of 1 millisecond, round away
435	n/a	# from zero to wait at least timeout seconds.
436	n/a	timeout = math.ceil(timeout * 1e3) * 1e-3
437	n/a
438	n/a	# epoll_wait() expects `maxevents` to be greater than zero;
439	n/a	# we want to make sure that `select()` can be called when no
440	n/a	# FD is registered.
441	n/a	max_ev = max(len(self._fd_to_key), 1)
442	n/a
443	n/a	ready = []
444	n/a	try:
445	n/a	fd_event_list = self._epoll.poll(timeout, max_ev)
446	n/a	except InterruptedError:
447	n/a	return ready
448	n/a	for fd, event in fd_event_list:
449	n/a	events = 0
450	n/a	if event & ~select.EPOLLIN:
451	n/a	events \|= EVENT_WRITE
452	n/a	if event & ~select.EPOLLOUT:
453	n/a	events \|= EVENT_READ
454	n/a
455	n/a	key = self._key_from_fd(fd)
456	n/a	if key:
457	n/a	ready.append((key, events & key.events))
458	n/a	return ready
459	n/a
460	n/a	def close(self):
461	n/a	self._epoll.close()
462	n/a	super().close()
463	n/a
464	n/a
465	n/a	if hasattr(select, 'devpoll'):
466	n/a
467	n/a	class DevpollSelector(_BaseSelectorImpl):
468	n/a	"""Solaris /dev/poll selector."""
469	n/a
470	n/a	def __init__(self):
471	n/a	super().__init__()
472	n/a	self._devpoll = select.devpoll()
473	n/a
474	n/a	def fileno(self):
475	n/a	return self._devpoll.fileno()
476	n/a
477	n/a	def register(self, fileobj, events, data=None):
478	n/a	key = super().register(fileobj, events, data)
479	n/a	poll_events = 0
480	n/a	if events & EVENT_READ:
481	n/a	poll_events \|= select.POLLIN
482	n/a	if events & EVENT_WRITE:
483	n/a	poll_events \|= select.POLLOUT
484	n/a	self._devpoll.register(key.fd, poll_events)
485	n/a	return key
486	n/a
487	n/a	def unregister(self, fileobj):
488	n/a	key = super().unregister(fileobj)
489	n/a	self._devpoll.unregister(key.fd)
490	n/a	return key
491	n/a
492	n/a	def select(self, timeout=None):
493	n/a	if timeout is None:
494	n/a	timeout = None
495	n/a	elif timeout <= 0:
496	n/a	timeout = 0
497	n/a	else:
498	n/a	# devpoll() has a resolution of 1 millisecond, round away from
499	n/a	# zero to wait at least timeout seconds.
500	n/a	timeout = math.ceil(timeout * 1e3)
501	n/a	ready = []
502	n/a	try:
503	n/a	fd_event_list = self._devpoll.poll(timeout)
504	n/a	except InterruptedError:
505	n/a	return ready
506	n/a	for fd, event in fd_event_list:
507	n/a	events = 0
508	n/a	if event & ~select.POLLIN:
509	n/a	events \|= EVENT_WRITE
510	n/a	if event & ~select.POLLOUT:
511	n/a	events \|= EVENT_READ
512	n/a
513	n/a	key = self._key_from_fd(fd)
514	n/a	if key:
515	n/a	ready.append((key, events & key.events))
516	n/a	return ready
517	n/a
518	n/a	def close(self):
519	n/a	self._devpoll.close()
520	n/a	super().close()
521	n/a
522	n/a
523	n/a	if hasattr(select, 'kqueue'):
524	n/a
525	n/a	class KqueueSelector(_BaseSelectorImpl):
526	n/a	"""Kqueue-based selector."""
527	n/a
528	n/a	def __init__(self):
529	n/a	super().__init__()
530	n/a	self._kqueue = select.kqueue()
531	n/a
532	n/a	def fileno(self):
533	n/a	return self._kqueue.fileno()
534	n/a
535	n/a	def register(self, fileobj, events, data=None):
536	n/a	key = super().register(fileobj, events, data)
537	n/a	try:
538	n/a	if events & EVENT_READ:
539	n/a	kev = select.kevent(key.fd, select.KQ_FILTER_READ,
540	n/a	select.KQ_EV_ADD)
541	n/a	self._kqueue.control([kev], 0, 0)
542	n/a	if events & EVENT_WRITE:
543	n/a	kev = select.kevent(key.fd, select.KQ_FILTER_WRITE,
544	n/a	select.KQ_EV_ADD)
545	n/a	self._kqueue.control([kev], 0, 0)
546	n/a	except BaseException:
547	n/a	super().unregister(fileobj)
548	n/a	raise
549	n/a	return key
550	n/a
551	n/a	def unregister(self, fileobj):
552	n/a	key = super().unregister(fileobj)
553	n/a	if key.events & EVENT_READ:
554	n/a	kev = select.kevent(key.fd, select.KQ_FILTER_READ,
555	n/a	select.KQ_EV_DELETE)
556	n/a	try:
557	n/a	self._kqueue.control([kev], 0, 0)
558	n/a	except OSError:
559	n/a	# This can happen if the FD was closed since it
560	n/a	# was registered.
561	n/a	pass
562	n/a	if key.events & EVENT_WRITE:
563	n/a	kev = select.kevent(key.fd, select.KQ_FILTER_WRITE,
564	n/a	select.KQ_EV_DELETE)
565	n/a	try:
566	n/a	self._kqueue.control([kev], 0, 0)
567	n/a	except OSError:
568	n/a	# See comment above.
569	n/a	pass
570	n/a	return key
571	n/a
572	n/a	def select(self, timeout=None):
573	n/a	timeout = None if timeout is None else max(timeout, 0)
574	n/a	max_ev = len(self._fd_to_key)
575	n/a	ready = []
576	n/a	try:
577	n/a	kev_list = self._kqueue.control(None, max_ev, timeout)
578	n/a	except InterruptedError:
579	n/a	return ready
580	n/a	for kev in kev_list:
581	n/a	fd = kev.ident
582	n/a	flag = kev.filter
583	n/a	events = 0
584	n/a	if flag == select.KQ_FILTER_READ:
585	n/a	events \|= EVENT_READ
586	n/a	if flag == select.KQ_FILTER_WRITE:
587	n/a	events \|= EVENT_WRITE
588	n/a
589	n/a	key = self._key_from_fd(fd)
590	n/a	if key:
591	n/a	ready.append((key, events & key.events))
592	n/a	return ready
593	n/a
594	n/a	def close(self):
595	n/a	self._kqueue.close()
596	n/a	super().close()
597	n/a
598	n/a
599	n/a	# Choose the best implementation, roughly:
600	n/a	# epoll\|kqueue\|devpoll > poll > select.
601	n/a	# select() also can't accept a FD > FD_SETSIZE (usually around 1024)
602	n/a	if 'KqueueSelector' in globals():
603	n/a	DefaultSelector = KqueueSelector
604	n/a	elif 'EpollSelector' in globals():
605	n/a	DefaultSelector = EpollSelector
606	n/a	elif 'DevpollSelector' in globals():
607	n/a	DefaultSelector = DevpollSelector
608	n/a	elif 'PollSelector' in globals():
609	n/a	DefaultSelector = PollSelector
610	n/a	else:
611	n/a	DefaultSelector = SelectSelector