Loop – event loop¶
-
class
uv.
Loop
(allocator=None, buffer_size=65536, default=False)[source]¶ The event loop is the central part of this library. It takes care of polling for IO and scheduling callbacks to be run based on different sources of events.
Raises: - RuntimeError – error while initializing global default loop
- UVError – error initializing the new event loop
Parameters: - allocator (uv.loop.Allocator) – read buffer allocator
- buffer_size (int) – size of the default allocators read buffer
- default (bool) – instantiate the default loop
-
classmethod
get_default
(instantiate=True, **keywords)[source]¶ Get the default (across multiple threads) event loop. Note that although this returns the same loop across multiple threads loops are not thread safe. Normally there is one thread running the default loop and others interfering with it trough
uv.Async
handles oruv.Loop.call_later()
.Parameters: instantiate (bool) – instantiate the default event loop if it does not exist Returns: global default loop Return type: Loop
-
classmethod
get_current
(instantiate=True, **keywords)[source]¶ Get the current (thread local) default event loop. Loops register themselves as current loop on instantiation and in their
uv.Loop.run()
method.Parameters: instantiate (bool) – instantiate a new loop if there is no current loop Returns: current thread’s default loop Return type: Loop
-
excepthook
= None¶ If an exception occurs during the execution of a callback this excepthook is called with the corresponding event loop and exception details. The default behavior is to print the traceback to stderr and stop the event loop. To override the default behavior assign a custom function to this attribute.
Note
If the excepthook raises an exception itself the program would be in an undefined state. Therefore it terminates with sys.exit(1) in that case immediately.
-
excepthook
(loop, exc_type, exc_value, exc_traceback) Parameters: - loop (uv.Loop) – corresponding event loop
- exc_type (type) – exception type (subclass of
BaseException
) - exc_value (BaseException) – exception instance
- exc_traceback (traceback) – traceback which encapsulates the call stack at the point where the exception originally occurred
Readonly: False Type: Callable[[uv.Loop, type, Exception, traceback.Traceback], None] -
-
exc_type
= None¶ Type of last exception handled by the excepthook.
Readonly: True Type: type
-
exc_value
= None¶ Instance of last exception handled by the excepthook.
Readonly: True Type: BaseException
-
exc_traceback
= None¶ Traceback of the last exception handled by the excepthook.
Readonly: True Type: traceback
-
alive
¶ True if there are active and referenced handles running on the loop, False otherwise.
Readonly: True Return type: bool
-
now
¶ Current internal timestamp in milliseconds. The timestamp increases monotonically from some arbitrary point in time.
Readonly: True Return type: int
-
fileno
()[source]¶ Get the file descriptor of the backend. This is only supported on kqueue, epoll and event ports.
Raises: - uv.UVError – error getting file descriptor
- uv.ClosedLoopError – loop has already been closed
Returns: backend file descriptor
Return type:
-
update_time
()[source]¶ Update the event loop’s concept of “now”. Libuv caches the current time at the start of the event loop tick in order to reduce the number of time-related system calls.
Raises: uv.ClosedLoopError – loop has already been closed Note
You won’t normally need to call this function unless you have callbacks that block the event loop for longer periods of time, where “longer” is somewhat subjective but probably on the order of a millisecond or more.
-
get_timeout
()[source]¶ Get the poll timeout. The return value is in milliseconds, or -1 for no timeout.
Raises: uv.ClosedLoopError – loop has already been closed Returns: backend timeout in milliseconds Return type: int
-
run
(mode=<RunModes.DEFAULT: 0>)[source]¶ Run the loop in the specified mode.
Raises: uv.ClosedLoopError – loop has already been closed Parameters: mode (uv.RunModes) – run mode Returns: run mode specific return value Return type: bool
-
stop
()[source]¶ Stop the event loop, causing
uv.Loop.run()
to end as soon as possible. This will happen not sooner than the next loop iteration. If this method was called before blocking for IO, the loop will not block for IO on this iteration.
-
close
()[source]¶ Closes all internal loop resources. This method must only be called once the loop has finished its execution or it will raise
uv.error.ResourceBusyError
.Note
Loops are automatically closed when they are garbage collected. However because the exact time this happens is non-deterministic you should close them explicitly.
Raises: - uv.UVError – error while closing the loop
- uv.error.ResourceBusyError – loop is currently running or there are pending operations
-
close_all_handles
(on_closed=None)[source]¶ Close all handles.
Parameters: on_closed (Callable[[uv.Handle], None]) – callback which should run after a handle has been closed (overrides the current callback if specified)
-
call_later
(callback, *arguments, **keywords)[source]¶ Schedule a callback to run at some later point in time. The callback does not keep the loop alive if there a no other active handles running on the loop.
This method is thread safe.
Parameters:
-
on_wakeup
()[source]¶ Called after the event loop has been woken up.
Warning
This method is only for internal purposes and is not part of the official API. You should never call it directly!
-
handle_exception
()[source]¶ Handle the current exception using the excepthook.
Warning
This method is only for internal purposes and is not part of the official API. You should never call it directly!
-
structure_set_pending
(structure)[source]¶ Add a structure to the set of pending structures.
Warning
This method is only for internal purposes and is not part of the official API. You should never call it directly!
-
class
uv.
RunModes
[source]¶ Run modes to control the behavior of
uv.Loop.run()
.-
DEFAULT
= None¶ Run the event loop until there are no more active and referenced handles or requests.
uv.Loop.run()
returns True ifuv.Loop.stop()
was called and there are still active handles or requests and False otherwise.Type: uv.RunModes
-
ONCE
= None¶ Poll for IO once. Note that
uv.Loop.run()
will block if there are no pending callbacks.uv.Loop.run()
returns True if there are still active handles or requests which means the event loop should run again sometime in the future.Type: uv.RunModes
-
NOWAIT
= None¶ Poll for IO once but do not block if there are no pending callbacks.
uv.Loop.run()
returns True if there are still active handles or requests which means the event loop should run again sometime in the future.Type: uv.RunModes
-
-
class
uv.loop.
Allocator
[source]¶ Abstract base class for read buffer allocators. Allows swappable allocation strategies and custom read result types.
Warning
This class exposes some details of the underlying CFFI based wrapper — use it with caution. Any errors in the allocator might lead to unpredictable behavior.
-
allocate
(handle, suggested_size, uv_buffer)[source]¶ Called if libuv needs a new read buffer. The allocated chunk of memory has to be assigned to uv_buf.base and the length of the chunk to uv_buf.len use
library.uv_buffer_set()
for assigning. Base might be NULL which triggers an ENOBUFS error in the read callback.Parameters:
-
finalize
(handle, length, uv_buffer)[source]¶ Called in the read callback to access the read buffer’s data. The result of this call is directly passed to the user’s read callback which allows to use a custom read result type.
Parameters: Returns: buffer’s data (default type is
bytes
)Return type: Any | bytes
-