Handle – handle base class¶
-
class
uv.
Handle
(loop, arguments=())[source]¶ 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.
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.
Raises: uv.LoopClosedError – loop has already been closed
Parameters: -
loop
¶ Loop the handle is running on.
Readonly: True Type: uv.Loop
-
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
¶ 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 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 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
-
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:
-
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)
-