uv_req_t — Base request

uv_req_t is the base type for all libuv request types.

Structures are aligned so that any libuv request can be cast to uv_req_t. All API functions defined here work with any request type.

Data types

type uv_req_t

The base libuv request structure.

type uv_any_req

Union of all request types.

enum uv_req_type

The kind of the libuv request.

typedef enum {
    UV_UNKNOWN_REQ = 0,
    UV_REQ,
    UV_CONNECT,
    UV_WRITE,
    UV_SHUTDOWN,
    UV_UDP_SEND,
    UV_FS,
    UV_WORK,
    UV_GETADDRINFO,
    UV_GETNAMEINFO,
    UV_REQ_TYPE_MAX,
} uv_req_type;

Public members

void *uv_req_t.data

Space for user-defined arbitrary data. libuv does not use this field.

uv_req_type uv_req_t.type

The uv_req_type, indicating the type of the request. Readonly.

API

UV_REQ_TYPE_MAP(iter_macro)

Macro that expands to a series of invocations of iter_macro for each of the request types. iter_macro is invoked with two arguments: the name of the uv_req_type element without the UV_ prefix, and the name of the corresponding structure type without the uv_ prefix and _t suffix.

int uv_cancel(uv_req_t *req)

Cancel a pending request. Fails if the request is executing or has finished executing. Write requests are an exception: cancellation of a write that is already in progress will attempt to interrupt it (the callback may report a partial write), and cancellation of an already-completed write is a successful no-op.

Returns 0 on success, or an error code < 0 on failure.

Only cancellation of uv_write_t, uv_fs_t, uv_getaddrinfo_t, uv_getnameinfo_t, uv_random_t and uv_work_t requests is currently supported.

Cancelled requests have their callbacks invoked some time in the future. It’s not safe to free the memory associated with the request until the callback is called.

Here is how cancellation is reported to the callback:

• A uv_fs_t request has its req->result field set to UV_ECANCELED.

• A uv_work_t, uv_getaddrinfo_t, uv_getnameinfo_t or uv_random_t request has its callback invoked with status == UV_ECANCELED.

• A uv_write_t request has its callback invoked with status == UV_ECANCELED. Use uv_write_nwritten() from the callback to determine how many bytes were written before cancellation. Fully cancelled writes (where no bytes were written) may have their callbacks called out of order with respect to other writes on the same stream. Note that cancelled writes may still succeed or fail with other errors if the kernel finished processing the write before the cancellation took effect.

size_t uv_req_size(uv_req_type type)

Returns the size of the given request type. Useful for FFI binding writers who don’t want to know the structure layout.

void *uv_req_get_data(const uv_req_t *req)

Returns req->data.

New in version 1.19.0.

void uv_req_set_data(uv_req_t *req, void *data)

Sets req->data to data.

New in version 1.19.0.

uv_req_type uv_req_get_type(const uv_req_t *req)

Returns req->type.

New in version 1.19.0.

const char *uv_req_type_name(uv_req_type type)

Returns the name for the equivalent struct for a given request type, e.g. “connect” (as in uv_connect_t) for UV_CONNECT.

If no such request type exists, this returns NULL.

New in version 1.19.0.