Handle – handle base classes

class uv.Handle[source]

Handles represent long-lived objects capable of performing certain operations while active. This is the abstract base class of all internal libuv and pure Python handles.

Note

Handles underlie a special garbage collection strategy which means they are not garbage collected as other objects. If a handle is able to do anything in the program for example calling a callback they are not garbage collected.

loop

Loop the handle is running on.

Readonly:True
Return type:uv.Loop
closing

Handle is already closed or is closing. This is True right after close has been called. Operations on a closed or closing handle will raise uv.ClosedHandleError.

Readonly:True
Return type:bool
closed

Handle has been closed. This is True right after the close callback has been called. It means all internal resources are freed and this handle is ready to be garbage collected.

Readonly:True
Return type:bool
active

Handle is active or not. What “active” means depends on the handle type:

uv.Async:
is always active and cannot be deactivated
uv.Pipe, uv.TCP, uv.UDP, …:
basically any handle dealing with IO is active when it is doing something involves IO like reading, writing, connecting or listening
uv.Check, uv.Idle, uv.Timer, …:
handle is active when it has been started and not yet stopped
Readonly:True
Type:bool
referenced

Handle is referenced or not. If the event loop runs in default mode it will exit when there are no more active and referenced handles left. This has nothing to do with CPython’s reference counting.

Readonly:False
Type:bool
reference()[source]

Reference the handle. If the event loop runs in default mode it will exit when there are no more active and referenced handles left. This has nothing to do with CPython’s reference counting. References are idempotent, that is, if a handle is referenced calling this method again will have not effect.

Raises:uv.ClosedHandleError – handle has already been closed or is closing
dereference()[source]

Dereference the handle. If the event loop runs in default mode it will exit when there are no more active and referenced handles left. This has nothing to do with CPython’s reference counting. References are idempotent, that is, if a handle is not referenced calling this method again will have not effect.

Raises:uv.ClosedHandleError – handle has already been closed or is closing
close(on_closed=None)[source]

Close the handle. Please make sure to call this method on any handle you do not need anymore. This method is idempotent, that is, if the handle is already closed or is closing calling it will have no effect at all.

In-progress requests, like connect or write requests, are cancelled and have their callbacks called asynchronously with uv.StatusCodes.ECANCELED.

After this method has been called on a handle no operations can be performed on it (they raise uv.ClosedHandleError).

Note

Handles are automatically closed when they are garbage collected. However because the exact time this happens is non-deterministic you should close all handles explicitly. Especially if they handle external resources.

Parameters:on_closed (Callable[[uv.Handle], None]) – callback which should run after the handle has been closed (overrides the current callback if specified)
class uv.UVHandle(loop, arguments=())[source]

Base class of all internal libuv based handles.

Raises:

uv.LoopClosedError – loop has already been closed

Parameters:
  • loop (uv.Loop) – loop where the handle should run on
  • arguments (tuple) – arguments passed to the libuv handle init function
on_closed

Callback which should run after the handle has been closed.

on_closed(handle)
Parameters:handle (uv.Handle) – handle which has been closed
Readonly:False
Type:Callable[[uv.Handle], None]
data

User-specific data of any type. This is necessary because of the usage of slots.

Readonly:False
Type:Any
allocator

Allocator used to allocate new read buffers for this handle.

Readonly:False
Type:uv.loop.Allocator
closing
Readonly:True
Type:bool
closed
Readonly:True
Type:bool
active
Readonly:True
Type:bool
referenced
Readonly:False
Type:bool
send_buffer_size

Size of the send buffer that the operating system uses for the socket. The following handles are supported: TCP and UDP handles on Unix and Windows, Pipe handles only on Unix. On all unsupported handles this will raise uv.UVError with error code EINVAL (uv.error.ArgumentError).

Note

Unlike libuv this library abstracts the different behaviours on Linux and other operating systems. This means, the size set is divided by two on Linux because Linux internally multiplies it by two.

Raises:
  • uv.UVError – error while getting/setting the send buffer size
  • uv.ClosedHandleError – handle has already been closed or is closing
Readonly:

False

Type:

int

receive_buffer_size

Size of the receive buffer that the operating system uses for the socket. The following handles are supported: TCP and UDP handles on Unix and Windows, Pipe handles only on Unix. On all unsupported handles this will raise uv.UVError with error code EINVAL (uv.error.ArgumentError).

Note

Unlike libuv this library abstracts the different behaviours on Linux and other operating systems. This means, the size set is divided by two on Linux because Linux internally multiplies it by two.

Raises:
  • uv.UVError – error while getting/setting the receive buffer size
  • uv.ClosedHandleError – handle has already been closed or is closing
Readonly:

False

Type:

int

fileno()[source]

Get the platform dependent file descriptor equivalent. The following handles are supported: TCP, UDP, TTY, Pipes and Poll. On all other handles this will raise uv.UVError with error code EINVAL (uv.error.ArgumentError).

If a handle does not have an attached file descriptor yet this method will raise uv.UVError with error code EBADF (uv.error.BadFileDescriptorError).

Warning

Be very careful when using this method. Libuv assumes it is in control of the file descriptor so any change to it may result in unpredictable malfunctions.

Raises:
  • uv.UVError – error while receiving fileno
  • uv.ClosedHandleError – handle has already been closed or is closing
Returns:

platform dependent file descriptor equivalent

Return type:

int

reference()[source]
Raises:uv.ClosedHandleError – handle has already been closed or is closing
dereference()[source]
Raises:uv.ClosedHandleError – handle has already been closed or is closing
close(on_closed=None)[source]
Parameters:on_closed (Callable[[uv.Handle], None]) – callback which should run after the handle has been closed (overrides the current callback if specified)
set_pending()[source]

Warning

This method is only for internal purposes and is not part of the official API. It deactivates the garbage collection for the handle which means the handle and the corresponding loop are excluded from garbage collection. You should never call it directly!

clear_pending()[source]

Warning

This method is only for internal purposes and is not part of the official API. It reactivates the garbage collection for the handle. You should never call it directly!