Loop – event loop

class uv.Loop(allocator=None, buffer_size=65536, default=False)

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)

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 or uv.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)

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

closed

True if and only if the loop has been closed.

Readonly:True Return type:bool

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

handles

Set of all handles running on the loop.

Readonly:True Return type:set

fileno()

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:

int

make_current()

Make the loop the current thread local default loop.

update_time()

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()

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>)

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()

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()

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)

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)

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:

• callback (callable) – callback which should run at some later point in time
• arguments (tuple) – arguments that should be passed to the callback
• keywords (dict) – keyword arguments that should be passed to the callback

reset_exception()

Reset the last exception caught by the excepthook.

on_wakeup()

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()

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)

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!

structure_clear_pending(structure)

Remove a structure from 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!

structure_is_pending(structure)

Return true if and only if the structure is pending.

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

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 if uv.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

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)

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:

• handle (uv.Handle) – handle caused the read
• suggested_size (int) – suggested buffer size
• uv_buffer (ffi.CData[uv_buf_t]) – uv target buffer

finalize(handle, length, uv_buffer)

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:

• handle (uv.Handle) – handle caused the read
• length (int) – length of bytes read
• uv_buffer (ffi.CData[uv_buf_t]) – uv buffer used for reading

Returns:

buffer’s data (default type is bytes)

Return type:

Any | bytes

class uv.loop.DefaultAllocator(buffer_size=65536)

Default read buffer allocator which only uses one buffer and copies the data to a python bytes object after reading.