diff -r d829111a27e5 -r 79291e383511 Doc/library/asyncio.rst --- a/Doc/library/asyncio.rst Thu Nov 28 17:09:16 2013 -0800 +++ b/Doc/library/asyncio.rst Fri Nov 29 15:22:08 2013 +0100 @@ -77,8 +77,178 @@ Getting an event loop The easiest way to get an event loop is to call the :func:`get_event_loop` function. +.. function:: get_event_loop() + + Get the event loop for current context. Returns an event loop object + implementing :class:`EventLoop` interface, or raises an exception in case no + event loop has been set for the current context and the current policy does + not specify to create one. It should never return ``None``. + + +.. class:: BaseEventLoop + + Base event loop. + + .. method:: call_at(when, callback, \*args) + + Like :meth:`call_later`, but uses an absolute time. + + .. method:: call_later(delay, callback, \*args) + + Arrange for a callback to be called at a given time. + + Return a :class:`Handle`: an opaque object with a cancel() method that + can be used to cancel the call. + + The delay can be an int or float, expressed in seconds. It is always a + relative time. + + Each callback will be called exactly once. If two callbacks are + scheduled for exactly the same time, it undefined which will be called + first. + + Any positional arguments after the callback will be passed to the + callback when it is called. + + .. method:: call_soon( callback, \*args) + + Arrange for a callback to be called as soon as possible. + + This operates as a FIFO queue, callbacks are called in the order in + which they are registered. Each callback will be called exactly once. + + Any positional arguments after the callback will be passed to the + callback when it is called. + + .. method: call_soon_threadsafe(callback, \*args) + + Like :meth:`call_soon`, but thread safe. + + .. method:: connect_read_pipe(protocol_factory, pipe) + + XXX + + .. method:: connect_write_pipe(protocol_factory, pipe): + + XXX + + .. method:: create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None) + + XXX + + * *protocol_factory* + * *host*, *port*: server host name and port number + * *server_hostname*: server hostname, *host* is used by default + * *sock*: :ref:`socket object ` + * *ssl*: ``True`` or :class:`ssl.SSLContext` + * *family*: socket family, ex: :data:`socket.AF_INET` + * *proto*: socket protocol + * *flags*: name resolution flags, one or several of the ``socket.AI_*`` + constants + * *local_addr*: local address + + See :func:`socket.socket` for *family* and *proto* parameters. + + See :func:`socket.getaddrinfo` for *flags* parameter. + + .. method:: create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0) + + XXX + + * *protocol_factory* + * *local_addr* + * *remote_addr* + * *family*, *proto* + * *flags* + + + .. method:: create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None) + + XXX + + * *protocol_factory* + * *host*, *port* + * *family* + * *flags* + * *sock* + * *backlog* : the maximum number of queued connections and should be at + least ``0``; the maximum value is system-dependent (usually ``5``), + the minimum value is forced to ``0``. + * *ssl*: ``True`` or :class:`ssl.SSLContext` + * *reuse_address*: if ``True``, set :data:`socket.SO_REUSEADDR` option + on the listening socket. Default value: ``True`` on POSIX systems, + ``False`` on Windows. + + .. method:: close() + + Close the event loop. + + This clears the queues and shuts down the executor, but does not wait for + the executor to finish. + + .. method:: getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0) + + XXX + + .. method:: getnameinfo(sockaddr, flags=0) + + XXX + + .. method:: is_running() + + Returns running status of event loop. + + .. method:: run_forever() + + Run until :meth:`stop` is called. + + .. method:: run_in_executor(executor, callback, \*args) + + XXX + + .. method:: run_until_complete(future) + + Run until the :class:`Future` is done. + + If the argument is a coroutine, it is wrapped in a :class:`Task`. + + Return the Future's result, or raise its exception. + + .. method:: set_default_executor(executor) + + XXX + + .. method:: stop() + + Stop running the event loop. + + Every callback scheduled before :meth:`stop` is called will run. + Callback scheduled after :meth:`stop` is called won't. However, those + callbacks will run if :meth:`run_forever` is called again later. + + .. method:: subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=False, shell=True, bufsize=0, \*\*kwargs) + + XXX + + See the constructor of the :class:`subprocess.Popen` class for parameters. + + .. method:: subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=False, shell=False, bufsize=0, \*\*kwargs) + + XXX + + See the constructor of the :class:`subprocess.Popen` class for parameters. + + .. method:: time() + + Return the time according to the event loop's clock. + + The clock :func:`time.monotonic` is used by default. + + .. XXX more docs + + Delayed calls ^^^^^^^^^^^^^ @@ -97,8 +267,8 @@ a different clock than :func:`time.time` Arrange for the *callback* to be called after the given *delay* seconds (either an int or float). - A "handle" is returned: an opaque object with a :meth:`cancel` method - that can be used to cancel the call. + A "handle" is returned: an opaque object with a :meth:`~Handle.cancel` + method that can be used to cancel the call. *callback* will be called exactly once per call to :meth:`call_later`. If two callbacks are scheduled for exactly the same time, it is