source3/include/async_req.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3    Infrastructure for async requests
   4    Copyright (C) Volker Lendecke 2008
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef __ASYNC_REQ_H__
  21 #define __ASYNC_REQ_H__
  22
  23 #include "includes.h"
  24
  25 /*
  26  * An async request moves between the following 4 states.
  27  */
  28 enum async_req_state {
  29         ASYNC_REQ_INIT,         /* we are creating the request */
  30         ASYNC_REQ_IN_PROGRESS,  /* we are waiting the request to complete */
  31         ASYNC_REQ_DONE,         /* the request is finished */
  32         ASYNC_REQ_ERROR };      /* an error has occured */
  33
  34 struct async_req {
  35         /* the external state - will be queried by the caller */
  36         enum async_req_state state;
  37
  38         /* a private pointer for use by the async function implementation */
  39         void *private_data;
  40
  41         /* print yourself, for debugging purposes */
  42         char *(*print)(TALLOC_CTX *mem_ctx, struct async_req *);
  43
  44         /* status code when finished */
  45         NTSTATUS status;
  46
  47         /* the event context we are using */
  48         struct event_context *event_ctx;
  49
  50         /* information on what to do on completion */
  51         struct {
  52                 void (*fn)(struct async_req *);
  53                 void *priv;
  54         } async;
  55 };
  56
  57 /*
  58  * Print an async_req structure for debugging purposes
  59  */
  60 char *async_req_print(TALLOC_CTX *mem_ctx, struct async_req *req);
  61
  62 /*
  63  * Create an async request
  64  */
  65 struct async_req *async_req_new(TALLOC_CTX *mem_ctx, struct event_context *ev);
  66
  67 /*
  68  * An async request has successfully finished, invoke the callback
  69  */
  70 void async_req_done(struct async_req *req);
  71
  72 /*
  73  * An async request has seen an error, invoke the callback
  74  */
  75 void async_req_error(struct async_req *req, NTSTATUS status);
  76
  77 /*
  78  * If a request is finished or ends in error even before it has the chance to
  79  * trigger the event loop, post a status. This creates an immediate timed
  80  * event to call the async function if there is any.
  81  */
  82 bool async_post_status(struct async_req *req, NTSTATUS status);
  83
  84 /*
  85  * Convenience helper to easily check alloc failure within a callback.
  86  *
  87  * Call pattern would be
  88  * p = talloc(mem_ctx, bla);
  89  * if (async_req_nomem(p, req)) {
  90  *      return;
  91  * }
  92  *
  93  */
  94 bool async_req_nomem(const void *p, struct async_req *req);
  95
  96 #endif