Python libuv CFFI Bindings’s documentation!

Contents:

Errors – exceptions and error handling

class uv.StatusCode[source]
SUCCESS = None

Success.

class uv.UVError(code, message=None)[source]
class uv.HandleClosedError[source]
class uv.LoopClosedError[source]

Handle – handle base class

class uv.Handle(uv_handle, loop=None)[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.

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:
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:
Readonly:

False

Type:

int

fileno()[source]

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:
Returns:

platform dependent file descriptor equivalent

Return type:

int

reference()[source]

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()[source]

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)[source]

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()[source]

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!

Async – async handle

class uv.Async(loop=None, callback=None)[source]

Async handles will wake-up the event loop from an other thread and run the given callback within the event loop’s thread. They are the only thread-safe handles.

Raises:

uv.UVError – error during the initialization of the handle

Parameters:
  • loop (uv.Loop) – event loop which should be used for the handle
  • callback ((uv.Async) -> None) – callback which should be called from within the event loop
callback

Callback which should be called from within the event loop.

callback(Async-Handle)
Readonly:False
Type:(uv.Async) -> None
send(callback=None)[source]

Wake-up the event loop and execute the callback afterwards. Multiple calls to this method are coalesced if they happen before the callback has been called. This means not every call will yield a execution of the callback.

Raises:
Parameters:

callback ((uv.Async) -> None) – callback which should be called from within the event loop

Check – check handle

class uv.Check(loop=None, callback=None)[source]

Check handles will run the given callback once per loop iteration, right after polling for IO.

Raises:

uv.UVError – error during the initialization of the handle

Parameters:
  • loop (Loop) – event loop which should be used for the handle
  • callback ((uv.Check) -> None) – callback which should be called right after polling for IO
callback

Callback which should be called after polling for IO.

callback(Check-Handle)
Readonly:False
Type:(uv.Check) -> None
start(callback=None)[source]

Starts the handle.

Raises:
Parameters:

callback ((uv.Check) -> None) – callback which should be called after polling for IO

stop()[source]

Stops the handle, the callback will no longer be called.

Raises:uv.UVError – error while stopping the handle

Idle – idle handle

class uv.Idle(loop=None, callback=None)[source]

Idle handles will run the given callback once per loop iteration, right before the uv.Prepare handles.

The notable difference with prepare handles is, that when there are active idle handles, the loop will perform a zero timeout poll instead of blocking for IO.

Raises:

uv.UVError – error during the initialization of the handle

Parameters:
  • loop (uv.Loop) – event loop which should be used for the handle
  • callback ((uv.Idle) -> None) – callback which should be called before prepare handles
callback

Callback which should be called before prepare handles.

callback(Idle-Handle)
Readonly:False
Type:(uv.Idle) -> None
start(callback=None)[source]

Starts the handle.

Raises:
Parameters:

callback ((uv.Idle) -> None) – callback which should be called before prepare handles

stop()[source]

Stops the handle, the callback will no longer be called.

Raises:uv.UVError – error while stopping the handle

Poll – poll handle

class uv.Poll(fd, loop=None, callback=None)[source]

Poll handles are used to watch file descriptors for readability and writability. The purpose of poll handles is to enable integrating external libraries that rely on the event loop to signal them about the socket status changes. Using them for any other purpose is not recommended. Use uv.TCP, uv.UDP, etc. instead, which provide faster an more scalable implementations, that what can be archived with uv.Poll, especially on Windows.

It is possible that poll handles occasionally signal that a file descriptor is readable or writable even when it is not. The user should therefore always be prepared to handle EAGAIN or equivalent when it attempts to read from or write to the fd.

It is not okay to have multiple active poll handles for the same socket, this can cause libuv to busyloop or otherwise malfunction.

Do not close a file descriptor while it is being polled by an active poll handle. This can cause the handle to report an error, but it might also start polling another socket. However the fd can be safely closed immediately after uv.Poll.stop() or uv.Handle.close() has been called.

Note

On Windows only sockets can be polled with uv.Poll handles. On Unix any file descriptor that would be accepted by poll(2) can be used.

Raises:

uv.UVError – error during the initialization of the handle

Parameters:
  • fd (int) – file descriptor which should be polled (is set to non-blocking mode)
  • loop (Loop) – event loop which should be used for the handle
  • callback ((uv.Poll, uv.StatusCode, int) -> None) – callback which should be called on IO events
fd

File descriptor the handle polls on.

Readonly:True
Type:int
callback

Callback which should be called on IO events.

callback(Poll-Handle, Status-Code, Event-Mask)
Readonly:False
Type:(uv.Poll, uv.StatusCode, int) -> None
start(events=<PollEvent.READABLE: 1>, callback=None)[source]

Starts polling the file descriptor for the given events. As soon as an event is detected the callback will be called with status code uv.StatusCode.SUCCESS and the detected events.

If an error happens while polling the callback gets called with status code < 0 which corresponds to a uv.StatusCode.

Calling this on a handle that is already active is fine. Doing so will update the events mask that is being watched for.

Raises:
Parameters:
  • events (int) – bitmask of events which should be polled for
  • callback ((uv.Poll, uv.StatusCode, int) -> None) – callback which should be called on IO events
stop()[source]

Stops the handle, the callback will no longer be called.

Raises:uv.UVError – error while stopping the handle
class uv.PollEvent[source]

Poll event types enumeration.

READABLE = None

File descriptor is readable.

Type:int
WRITABLE = None

File descriptor is writable.

Type:int

Prepare – poll handle

class uv.Prepare(loop=None, callback=None)[source]

Prepare handles will run the given callback once per loop iteration, right before polling for IO.

Raises:

uv.UVError – error during the initialization of the handle

Parameters:
  • loop (Loop) – event loop which should be used for the handle
  • callback ((uv.Prepare) -> None) – callback which should be called right before polling for IO
callback

Callback which should be called before polling for IO.

callback(Prepare-Handle)
Readonly:False
Type:(uv.Prepare) -> None
start(callback=None)[source]

Starts the handle.

Raises:
Parameters:

callback ((uv.Prepare) -> None) – callback which should be called before polling for IO

stop()[source]

Stops the handle, the callback will no longer be called.

Raises:uv.UVError – error while stopping the handle

Signal – signal handle

class uv.Signal(loop=None, callback=None)[source]

Signal handles implement Unix style signal handling on a per-event loop bases. Reception of the generic uv.Signals is emulated on Windows. Watchers for other signals can be successfully created, but these signals are never received.

Note

On Linux SIGRT0 and SIGRT1 (signals 32 and 33) are used by the NPTL pthreads library to manage threads. Installing watchers for those signals will lead to unpredictable behavior and is strongly discouraged. Future versions of libuv may simply reject them.

Raises:

uv.UVError – error during the initialization of the handle

Parameters:
  • loop (Loop) – event loop which should be used for the handle
  • callback ((uv.Signal, int) -> None) – callback which should be called on signal delivery
callback

Callback which should be called on signal delivery.

callback(Signal-Handle, Signal-Number)
Readonly:False
Type:(uv.Signal, int) -> None
signum

Signal being monitored by this handle.

Raises:uv.HandleClosedError – handle has already been closed or is closing
Readonly:True
Return type:int
start(signum, callback=None)[source]

Starts the handle.

Raises:
Parameters:
  • signum (int) – signal number which should be monitored
  • callback ((uv.Signal) -> None) – callback which should be called on signal delivery
stop()[source]

Stops the handle, the callback will no longer be called.

Raises:uv.UVError – error while stopping the handle
class uv.Signals[source]

Generic signals enumeration.

SIGINT = None

Is normally delivered when the user presses CTRL+C. However it is not generated when terminal is in raw mode.

Type:int
SIGBREAK = None

Is delivered when the user presses CTRL+BREAK.

Type:int
SIGHUP = None

Is generated when the user closes the console window. After that the OS might terminate the program after a few seconds.

Type:int
SIGWINCH = None

Is generated when the console window has been resized. On Windows libuv emulates SIGWINCH when the program uses a uv.TTY handle to write to the console. It may not always be delivered in a timely manner, because libuv will only detect changes when the cursor is being moved. When a readable uv.TTY handle is used in raw mode, resizing the console buffer will also trigger SIGWINCH.

Type:int

Timer – timer handle

class uv.Timer(loop=None, callback=None)[source]

Timer handles are used to schedule callbacks to be called in the future.

Raises:

uv.UVError – error during the initialization of the handle

Parameters:
  • loop (Loop) – event loop which should be used for the handle
  • callback ((uv.Timer) -> None) – callback which should be called on timeout
callback

Callback which should be called on timeout.

callback(Timer-Handle)
Readonly:False
Type:(uv.Timer) -> None
repeat

The repeat interval value in milliseconds. The timer will be scheduled to run on the given interval, regardless of the callback execution duration, and will follow normal timer semantics in the case of time-slice overrun.

For example, if a 50ms repeating timer first runs for 17ms, it will be scheduled to run again 33ms later. If other tasks consume more than the 33ms following the first timer callback, then the callback will run as soon as possible.

Note

If the repeat value is set from a timer callback it does not immediately take effect. If the timer was non-repeating before, it will have been stopped. If it was repeating, then the old repeat value will have been used to schedule the next timeout.

Raises:uv.HandleClosedError – handle has already been closed or is closing
Readonly:False
Return type:int
again()[source]

Stop the timer, and if it is repeating restart it using the repeat value as the timeout. If the timer has never been started before it raises uv.UVError with uv.StatusCode.EINVAL.

Raises:
start(timeout, callback=None, repeat=0)[source]

Starts the timer. If timeout is zero, the callback fires on the next event loop iteration. If repeat is non-zero, the callback fires first after timeout milliseconds and then repeatedly after repeat milliseconds.

Raises:
Parameters:
  • timeout (int) – timeout which should be used (in milliseconds)
  • callback ((uv.Timer) -> None) – callback which should be called on timeout
  • repeat (int) – repeat interval which should be set (in milliseconds)
stop()[source]

Stops the handle, the callback will no longer be called.

Raises:uv.UVError – error while stopping the handle

Indices and tables