summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
Diffstat (limited to 'lib')
-rw-r--r--lib/tevent/tevent.h67
1 files changed, 45 insertions, 22 deletions
diff --git a/lib/tevent/tevent.h b/lib/tevent/tevent.h
index 82c14831e5..90c9fca03f 100644
--- a/lib/tevent/tevent.h
+++ b/lib/tevent/tevent.h
@@ -509,16 +509,15 @@ int tevent_set_debug_stderr(struct tevent_context *ev);
* @defgroup tevent_request The tevent request functions.
* @ingroup tevent
*
- * 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.
+ * A tevent_req represents an asynchronous computation. Such a
+ * computation is started by a computation_send function. When it is
+ * finished, its result can be received by a computation_recv
+ * function.
*
- * 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.
+ * It is up to the user of the async computation to talloc_free it
+ * after it has finished. If an async computation should be aborted,
+ * the tevent_req structure can be talloc_free'ed. After it has
+ * finished, it should talloc_free'ed by the API user.
*
* @{
*/
@@ -583,9 +582,17 @@ void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt
#ifdef DOXYGEN
/**
- * @brief Get the private data casted to the given type for a callback from
+ * @brief Get the private data cast to the given type for a callback from
* a tevent request structure.
*
+ * @code
+ * static void computation_done(struct tevent_req *subreq) {
+ * struct tevent_req *req = tevent_req_callback_data(subreq, struct tevent_req);
+ * struct computation_state *state = tevent_req_data(req, struct computation_state);
+ * .... more things, eventually maybe call tevent_req_done(req);
+ * }
+ * @endcode
+ *
* @param[in] req The structure to get the callback data from.
*
* @param[in] type The type of the private callback data to get.
@@ -621,9 +628,11 @@ void *tevent_req_callback_data_void(struct tevent_req *req);
*
* @param[in] req The structure to get the private data from.
*
+ * @param[in] type The type of the private data
+ *
* @return The private data or NULL if not set.
*/
-void *tevent_req_data(struct tevent_req *req);
+void *tevent_req_data(struct tevent_req *req, #type);
#else
void *_tevent_req_data(struct tevent_req *req);
#define tevent_req_data(_req, _type) \
@@ -755,22 +764,22 @@ bool _tevent_req_cancel(struct tevent_req *req, const char *location);
/**
* @brief Create an async tevent request.
*
- * The new async request will be initialized in state ASYNC_REQ_IN_PROGRESS.
- *
- * @param[in] mem_ctx The memory context for the result.
+ * The new async request will be initialized in state TEVENT_REQ_IN_PROGRESS.
*
- * @param[in] pstate The private state of the request.
- *
- * @param[in] state_size The size of the private state of the request.
+ * @code
+ * struct tevent_req *req;
+ * struct computation_state *state;
+ * req = tevent_req_create(mem_ctx, &state, struct computation_state);
+ * @endcode
*
+ * @param[in] mem_ctx The memory context for the result.
+ * @param[in] pstate Pointer to the private request state.
* @param[in] type The name of the request.
*
* @return A new async request. NULL on error.
*/
struct tevent_req *tevent_req_create(TALLOC_CTX *mem_ctx,
- void *pstate,
- size_t state_size,
- const char *type);
+ void **pstate, #type);
#else
struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
void *pstate,
@@ -904,7 +913,7 @@ bool _tevent_req_nomem(const void *p,
* @brief 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 request without waiting for an external event, or it can not 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
@@ -961,7 +970,21 @@ bool tevent_req_poll(struct tevent_req *req,
struct tevent_context *ev);
/**
- * @brief Get the tevent request and the actual error code you've set.
+ * @brief Get the tevent request and the actual error set by
+ * tevent_req_error.
+ *
+ * @code
+ * int computation_recv(struct tevent_req *req, uint64_t *perr)
+ * {
+ * enum tevent_req_state state;
+ * uint64_t err;
+ * if (tevent_req_is_error(req, &state, &err)) {
+ * *perr = err;
+ * return -1;
+ * }
+ * return 0;
+ * }
+ * @endcode
*
* @param[in] req The tevent request to get the error from.
*