The tevent request functions.
[The tevent API]

This represents an async request being processed by callbacks via an event context. More...

Enumerations
enum	tevent_req_state { TEVENT_REQ_INIT, TEVENT_REQ_IN_PROGRESS, TEVENT_REQ_DONE, TEVENT_REQ_USER_ERROR, TEVENT_REQ_TIMED_OUT, TEVENT_REQ_NO_MEMORY, TEVENT_REQ_RECEIVED }
	An async request moves between the following 4 states:. More...
Functions
void	tevent_req_set_print_fn (struct tevent_req *req, tevent_req_print_fn fn)
	This function sets a print function for the given request.
char *	tevent_req_default_print (struct tevent_req req, TALLOC_CTX mem_ctx)
	The default print function for creating debug messages.
char *	tevent_req_print (TALLOC_CTX mem_ctx, struct tevent_req req)
	Print an tevent_req structure in debug messages.
void	tevent_req_set_cancel_fn (struct tevent_req *req, tevent_req_cancel_fn fn)
	This function sets a cancel function for the given tevent request.
bool	tevent_req_cancel (struct tevent_req *req)
	Try to cancel the given tevent request.
struct tevent_req *	tevent_req_create (TALLOC_CTX mem_ctx, void pstate, size_t state_size, const char *type)
	Create an async tevent request.
void	tevent_req_done (struct tevent_req *req)
	An async request has successfully finished.
bool	tevent_req_error (struct tevent_req *req, uint64_t error)
	An async request has seen an error.
bool	tevent_req_nomem (const void p, struct tevent_req req)
	Helper function for nomem check.
struct tevent_req *	tevent_req_post (struct tevent_req req, struct tevent_context ev)
	Finish a request before the caller had the change to set the callback.
bool	tevent_req_is_in_progress (struct tevent_req *req)
	Check if the given request is still in progress.
bool	tevent_req_poll (struct tevent_req req, struct tevent_context ev)
	Actively poll for the given request to finish.
void	tevent_req_received (struct tevent_req *req)
	Use as the last action of a _recv() function.

Detailed Description

This represents an async request being processed by callbacks via an event context.

A user can issue for example a write request to a socket, giving an implementation function the fd, the buffer and the number of bytes to transfer. The function issuing the request will immediately return without blocking most likely without having sent anything. The API user then fills in req->async.fn and req->async.private_data, functions that are called when the request is finished.

It is up to the user of the async request to talloc_free it after it has finished. This can happen while the completion function is called.

Enumeration Type Documentation

enum tevent_req_state

An async request moves between the following 4 states:.

Enumerator:

TEVENT_REQ_INIT	we are creating the request
TEVENT_REQ_IN_PROGRESS	we are waiting the request to complete
TEVENT_REQ_DONE	the request is finished
TEVENT_REQ_USER_ERROR	A user error has occured.
TEVENT_REQ_TIMED_OUT	Request timed out.
TEVENT_REQ_NO_MEMORY	No memory in between.
TEVENT_REQ_RECEIVED	the request is already received by the caller

Function Documentation

bool tevent_req_cancel ( struct tevent_req * req )

Try to cancel the given tevent request.

This function can be used to cancel the given request.

It is only possible to cancel a request when the implementation has registered a cancel function via the tevent_req_set_cancel_fn().

Parameters:

[in] req The request to use.

Returns:: This function returns true is the request is cancelable, othererwise false is returned.

Note:: Even if the function returns true, the caller need to wait for the function to complete normally. Only the _recv() function of the given request indicates if the request was really canceled.

struct tevent_req* tevent_req_create	(	TALLOC_CTX *	mem_ctx,
		void *	pstate,
		size_t	state_size,
		const char *	type
	)			`[read]`

Create an async tevent request.

The new async request will be initialized in state ASYNC_REQ_IN_PROGRESS.

Parameters:

`[in]`	mem_ctx	The memory context for the result.
`[in]`	pstate	The private state of the request.
`[in]`	state_size	The size of the private state of the request.
`[in]`	type	The name of the request.

Returns:: A new async request. NULL on error.

char* tevent_req_default_print	(	struct tevent_req *	req,
		TALLOC_CTX *	mem_ctx
	)

The default print function for creating debug messages.

The function should not be used by users of the async API, but custom print function can use it and append custom text to the string.

Parameters:

`[in]`	req	The request to be printed.
`[in]`	mem_ctx	The memory context for the result.

Returns:: Text representation of request.

void tevent_req_done ( struct tevent_req * req )

An async request has successfully finished.

This function is to be used by implementors of async requests. When a request is successfully finished, this function calls the user's completion function.

Parameters:

[in] req The finished request.

bool tevent_req_error	(	struct tevent_req *	req,
		uint64_t	error
	)

An async request has seen an error.

This function is to be used by implementors of async requests. When a request can not successfully completed, the implementation should call this function with the appropriate status code.

If error is 0 the function returns false and does nothing more.

Parameters:

`[in]`	req	The request with an error.
`[in]`	error	The error code.

Returns:: On success true is returned, false if error is 0.

 int error = first_function();
 if (tevent_req_error(req, error)) {
      return;
 }

 error = second_function();
 if (tevent_req_error(req, error)) {
      return;
 }

 tevent_req_done(req);
 return;

bool tevent_req_is_in_progress ( struct tevent_req * req )

Check if the given request is still in progress.

It is typically used by sync wrapper functions.

This function destroys the attached private data.

Parameters:

[in] req The request to poll.

Returns:: The boolean form of "is in progress".

bool tevent_req_nomem	(	const void *	p,
		struct tevent_req *	req
	)

Helper function for nomem check.

Convenience helper to easily check alloc failure within a callback implementing the next step of an async request.

Parameters:

`[in]`	p	The pointer to be checked.
`[in]`	req	The request being processed.

 p = talloc(mem_ctx, bla);
 if (tevent_req_nomem(p, req)) {
      return;
 }

bool tevent_req_poll	(	struct tevent_req *	req,
		struct tevent_context *	ev
	)

Actively poll for the given request to finish.

This function is typically used by sync wrapper functions.

Parameters:

`[in]`	req	The request to poll.
`[in]`	ev	The tevent_context to be used.

Returns:: On success true is returned. If a critical error has happened in the tevent loop layer false is returned. This is not the return value of the given request!

Note:: This should only be used if the given tevent context was created by the caller, to avoid event loop nesting.

 req = tstream_writev_queue_send(mem_ctx,
                                 ev_ctx,
                                 tstream,
                                 send_queue,
                                 iov, 2);
 ok = tevent_req_poll(req, tctx->ev);
 rc = tstream_writev_queue_recv(req, &sys_errno);
 TALLOC_FREE(req);

struct tevent_req* tevent_req_post	(	struct tevent_req *	req,
		struct tevent_context *	ev
	)			`[read]`

Finish a request before the caller had the change to set the callback.

An implementation of an async request might find that it can either finish the request without waiting for an external event, or it can't even start the engine. To present the illusion of a callback to the user of the API, the implementation can call this helper function which triggers an immediate timed event. This way the caller can use the same calling conventions, independent of whether the request was actually deferred.

Parameters:

`[in]`	req	The finished request.
`[in]`	ev	The tevent_context for the timed event.

Returns:: The given request will be returned.

char* tevent_req_print	(	TALLOC_CTX *	mem_ctx,
		struct tevent_req *	req
	)

Print an tevent_req structure in debug messages.

This function should be used by callers of the async API.

Parameters:

`[in]`	mem_ctx	The memory context for the result.
`[in]`	req	The request to be printed.

Returns:: Text representation of request.

void tevent_req_received ( struct tevent_req * req )

Use as the last action of a _recv() function.

This function destroys the attached private data.

Parameters:

[in] req The finished request.

void tevent_req_set_cancel_fn	(	struct tevent_req *	req,
		tevent_req_cancel_fn	fn
	)

This function sets a cancel function for the given tevent request.

This function can be used to setup a cancel function for the given request. This will be triggered if the tevent_req_cancel() function was called on the given request.

Parameters:

`[in]`	req	The request to use.
`[in]`	fn	A pointer to the cancel function.

void tevent_req_set_print_fn	(	struct tevent_req *	req,
		tevent_req_print_fn	fn
	)

This function sets a print function for the given request.

This function can be used to setup a print function for the given request. This will be triggered if the tevent_req_print() function was called on the given request.

Parameters:

`[in]`	req	The request to use.
`[in]`	fn	A pointer to the print function

Note:: This function should only be used for debugging.

The tevent request functions. [The tevent API]

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation

The tevent request functions.
[The tevent API]