lib/tevent/tevent_req.c

   1 /*
   2    Unix SMB/CIFS implementation.
   3    Infrastructure for async requests
   4    Copyright (C) Volker Lendecke 2008
   5    Copyright (C) Stefan Metzmacher 2009
   6
   7      ** NOTE! The following LGPL license applies to the tevent
   8      ** library. This does NOT imply that all of Samba is released
   9      ** under the LGPL
  10
  11    This library is free software; you can redistribute it and/or
  12    modify it under the terms of the GNU Lesser General Public
  13    License as published by the Free Software Foundation; either
  14    version 3 of the License, or (at your option) any later version.
  15
  16    This library is distributed in the hope that it will be useful,
  17    but WITHOUT ANY WARRANTY; without even the implied warranty of
  18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19    Lesser General Public License for more details.
  20
  21    You should have received a copy of the GNU Lesser General Public
  22    License along with this library; if not, see <http://www.gnu.org/licenses/>.
  23 */
  24
  25 #include "replace.h"
  26 #include "tevent.h"
  27 #include "tevent_internal.h"
  28 #include "tevent_util.h"
  29
  30 /**
  31  * @brief The default print function for creating debug messages
  32  * @param[in] req       The request to be printed
  33  * @param[in] mem_ctx   The memory context for the result
  34  * @retval              Text representation of req
  35  *
  36  * The function should not be used by users of the asynx API,
  37  * but custom print function can use it and append custom text
  38  * to the string.
  39  */
  40
  41 char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx)
  42 {
  43         return talloc_asprintf(mem_ctx,
  44                                "tevent_req[%p/%s]: state[%d] error[%lld (0x%llX)] "
  45                                " state[%s (%p)] timer[%p]",
  46                                req, req->internal.location,
  47                                req->internal.state,
  48                                (unsigned long long)req->internal.error,
  49                                (unsigned long long)req->internal.error,
  50                                talloc_get_name(req->data),
  51                                req->data,
  52                                req->internal.timer
  53                                );
  54 }
  55
  56 /**
  57  * @brief Print an tevent_req structure in debug messages
  58  * @param[in] mem_ctx   The memory context for the result
  59  * @param[in] req       The request to be printed
  60  * @retval              Text representation of req
  61  *
  62  * This function should be used by callers of the async API
  63  */
  64
  65 char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req)
  66 {
  67         if (!req->private_print) {
  68                 return tevent_req_default_print(req, mem_ctx);
  69         }
  70
  71         return req->private_print(req, mem_ctx);
  72 }
  73
  74 /**
  75  * @brief Create an async request
  76  * @param[in] mem_ctx   The memory context for the result
  77  * @param[in] ev        The event context this async request will be driven by
  78  * @retval              A new async request
  79  *
  80  * The new async request will be initialized in state ASYNC_REQ_IN_PROGRESS
  81  */
  82
  83 struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
  84                                     void *pdata,
  85                                     size_t data_size,
  86                                     const char *type,
  87                                     const char *location)
  88 {
  89         struct tevent_req *req;
  90         void **ppdata = (void **)pdata;
  91         void *data;
  92
  93         req = talloc_zero(mem_ctx, struct tevent_req);
  94         if (req == NULL) {
  95                 return NULL;
  96         }
  97         req->internal.private_type      = type;
  98         req->internal.location          = location;
  99         req->internal.state             = TEVENT_REQ_IN_PROGRESS;
 100
 101         data = talloc_size(req, data_size);
 102         if (data == NULL) {
 103                 talloc_free(req);
 104                 return NULL;
 105         }
 106         talloc_set_name_const(data, type);
 107
 108         req->data = data;
 109
 110         *ppdata = data;
 111         return req;
 112 }
 113
 114 static void tevent_req_finish(struct tevent_req *req, enum tevent_req_state state)
 115 {
 116         req->internal.state = state;
 117         if (req->async.fn != NULL) {
 118                 req->async.fn(req);
 119         }
 120 }
 121
 122 /**
 123  * @brief An async request has successfully finished
 124  * @param[in] req       The finished request
 125  *
 126  * async_req_done is to be used by implementors of async requests. When a
 127  * request is successfully finished, this function calls the user's completion
 128  * function.
 129  */
 130
 131 void tevent_req_done(struct tevent_req *req)
 132 {
 133         tevent_req_finish(req, TEVENT_REQ_DONE);
 134 }
 135
 136 /**
 137  * @brief An async request has seen an error
 138  * @param[in] req       The request with an error
 139  * @param[in] error     The error code
 140  *
 141  * tevent_req_done is to be used by implementors of async requests. When a
 142  * request can not successfully completed, the implementation should call this
 143  * function with the appropriate status code.
 144  *
 145  * If error is 0 the function returns false and does nothing more.
 146  *
 147  * Call pattern would be
 148  * \code
 149  * int error = first_function();
 150  * if (tevent_req_error(req, error)) {
 151  *      return;
 152  * }
 153  *
 154  * error = second_function();
 155  * if (tevent_req_error(req, error)) {
 156  *      return;
 157  * }
 158  *
 159  * tevent_req_done(req);
 160  * return;
 161  * \endcode
 162  */
 163
 164 bool tevent_req_error(struct tevent_req *req, uint64_t error)
 165 {
 166         if (error == 0) {
 167                 return false;
 168         }
 169
 170         req->internal.error = error;
 171         tevent_req_finish(req, TEVENT_REQ_USER_ERROR);
 172         return true;
 173 }
 174
 175 /**
 176  * @brief Helper function for nomem check
 177  * @param[in] p         The pointer to be checked
 178  * @param[in] req       The request being processed
 179  *
 180  * Convenience helper to easily check alloc failure within a callback
 181  * implementing the next step of an async request.
 182  *
 183  * Call pattern would be
 184  * \code
 185  * p = talloc(mem_ctx, bla);
 186  * if (tevent_req_nomem(p, req)) {
 187  *      return;
 188  * }
 189  * \endcode
 190  */
 191
 192 bool tevent_req_nomem(const void *p, struct tevent_req *req)
 193 {
 194         if (p != NULL) {
 195                 return false;
 196         }
 197         tevent_req_finish(req, TEVENT_REQ_NO_MEMORY);
 198         return true;
 199 }
 200
 201 /**
 202  * @brief Timed event callback
 203  * @param[in] ev        Event context
 204  * @param[in] te        The timed event
 205  * @param[in] now       zero time
 206  * @param[in] priv      The async request to be finished
 207  */
 208 static void tevent_req_trigger(struct tevent_context *ev,
 209                                struct tevent_timer *te,
 210                                struct timeval zero,
 211                                void *private_data)
 212 {
 213         struct tevent_req *req = talloc_get_type(private_data,
 214                                  struct tevent_req);
 215
 216         talloc_free(req->internal.trigger);
 217         req->internal.trigger = NULL;
 218
 219         tevent_req_finish(req, req->internal.state);
 220 }
 221
 222 /**
 223  * @brief Finish a request before the caller had the change to set the callback
 224  * @param[in] req       The finished request
 225  * @param[in] ev        The tevent_context for the timed event
 226  * @retval              On success req will be returned,
 227  *                      on failure req will be destroyed
 228  *
 229  * An implementation of an async request might find that it can either finish
 230  * the request without waiting for an external event, or it can't even start
 231  * the engine. To present the illusion of a callback to the user of the API,
 232  * the implementation can call this helper function which triggers an
 233  * immediate timed event. This way the caller can use the same calling
 234  * conventions, independent of whether the request was actually deferred.
 235  */
 236
 237 struct tevent_req *tevent_req_post(struct tevent_req *req,
 238                                    struct tevent_context *ev)
 239 {
 240         req->internal.trigger = tevent_add_timer(ev, req, tevent_timeval_zero(),
 241                                                  tevent_req_trigger, req);
 242         if (!req->internal.trigger) {
 243                 talloc_free(req);
 244                 return NULL;
 245         }
 246
 247         return req;
 248 }
 249
 250 bool tevent_req_is_in_progress(struct tevent_req *req)
 251 {
 252         if (req->internal.state == TEVENT_REQ_IN_PROGRESS) {
 253                 return true;
 254         }
 255
 256         return false;
 257 }
 258
 259 /**
 260  * @brief This function destroys the attached private data
 261  * @param[in] req       The finished request
 262  *
 263  * This function can be called as last action of a _recv()
 264  * function, it destroys the data attached to the tevent_req.
 265  */
 266 void tevent_req_received(struct tevent_req *req)
 267 {
 268         talloc_free(req->data);
 269         req->data = NULL;
 270         req->private_print = NULL;
 271
 272         talloc_free(req->internal.trigger);
 273         req->internal.trigger = NULL;
 274         talloc_free(req->internal.timer);
 275         req->internal.timer = NULL;
 276
 277         req->internal.state = TEVENT_REQ_RECEIVED;
 278 }
 279
 280 bool tevent_req_poll(struct tevent_req *req,
 281                      struct tevent_context *ev)
 282 {
 283         while (tevent_req_is_in_progress(req)) {
 284                 int ret;
 285
 286                 ret = tevent_loop_once(ev);
 287                 if (ret != 0) {
 288                         return false;
 289                 }
 290         }
 291
 292         return true;
 293 }
 294
 295 bool tevent_req_is_error(struct tevent_req *req, enum tevent_req_state *state,
 296                         uint64_t *error)
 297 {
 298         if (req->internal.state == TEVENT_REQ_DONE) {
 299                 return false;
 300         }
 301         if (req->internal.state == TEVENT_REQ_USER_ERROR) {
 302                 *error = req->internal.error;
 303         }
 304         *state = req->internal.state;
 305         return true;
 306 }
 307
 308 static void tevent_req_timedout(struct tevent_context *ev,
 309                                struct tevent_timer *te,
 310                                struct timeval now,
 311                                void *private_data)
 312 {
 313         struct tevent_req *req = talloc_get_type(private_data,
 314                                  struct tevent_req);
 315
 316         talloc_free(req->internal.timer);
 317         req->internal.timer = NULL;
 318
 319         tevent_req_finish(req, TEVENT_REQ_TIMED_OUT);
 320 }
 321
 322 bool tevent_req_set_endtime(struct tevent_req *req,
 323                             struct tevent_context *ev,
 324                             struct timeval endtime)
 325 {
 326         talloc_free(req->internal.timer);
 327
 328         req->internal.timer = tevent_add_timer(ev, req, endtime,
 329                                                tevent_req_timedout,
 330                                                req);
 331         if (tevent_req_nomem(req->internal.timer, req)) {
 332                 return false;
 333         }
 334
 335         return true;
 336 }
 337
 338 void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt)
 339 {
 340         req->async.fn = fn;
 341         req->async.private_data = pvt;
 342 }
 343
 344 void *_tevent_req_callback_data(struct tevent_req *req)
 345 {
 346         return req->async.private_data;
 347 }
 348
 349 void *_tevent_req_data(struct tevent_req *req)
 350 {
 351         return req->data;
 352 }
 353
 354 void tevent_req_set_print_fn(struct tevent_req *req, tevent_req_print_fn fn)
 355 {
 356         req->private_print = fn;
 357 }