Handle – handle base class

class uv.Handle(uv_handle, loop=None)

Handles represent long-lived objects capable of performing certain operations while active. This is the base class of all handles except the file and SSL handle, which are pure Python.

Raises:

uv.LoopClosedError – loop has already been closed

Parameters:

• loop (Loop) – loop where the handle should run on
• uv_handle (ffi.CData) – allocated c struct for this handle

loop

Loop where the handle is running on.

Readonly:True Type:Loop

on_closed

Callback which should be called after the handle has been closed.

Readonly:False Type:(Handle) -> None

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 Type:bool

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.HandleClosedError.

Readonly:True Type:bool

active

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

• 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

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 StatusCode.EINVAL.

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.HandleClosedError – 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 StatusCode.EINVAL.

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.HandleClosedError – handle has already been closed or is closing

Readonly:

False

Type:

int

fileno()

Gets 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 StatusCode.EINVAL.

If a handle does not have an attached file descriptor yet this method will raise uv.UVError with StatusCode.EBADF.

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.HandleClosedError – handle has already been closed or is closing

Returns:

platform dependent file descriptor equivalent

Return type:

int

reference()

References 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 already referenced calling this method again will have not effect.

Raises:uv.HandleClosedError – handle has already been closed or is closing

dereference()

Dereferences 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.HandleClosedError – handle has already been closed or is closing

close(on_closed=None)

Closes the handle and frees all resources afterwards. Please make sure to call this method on any handle you do not need anymore. Handles do not close automatically and are also not garbage collected unless you have closed them exlicitly (explicit is better than implicit). This method is idempotent, that is, if the handle is already closed or is closing calling this method will have no effect.

In-progress requests, like uv.ConnectRequest or uv.WriteRequest, are cancelled and have their callbacks called asynchronously with StatusCode.ECANCELED

After this method has been called on a handle no other operations can be performed on it, they will raise uv.HandleClosedError.

Parameters:on_closed ((Handle) -> None) – callback called after the handle has been closed

destroy()

Warning

This method is used internally to free all allocated C resources and make sure there are no references from Python anymore to those objects after the handle has been closed. You should never call it directly!