mojo/public/c/environment/async_waiter.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_
   6 #define MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_
   7
   8 #include "mojo/public/c/system/types.h"
   9
  10 typedef uintptr_t MojoAsyncWaitID;
  11
  12 typedef void (*MojoAsyncWaitCallback)(void* closure, MojoResult result);
  13
  14 // Functions for asynchronously waiting (and cancelling asynchronous waits) on a
  15 // handle.
  16 //
  17 // Thread-safety:
  18 //   - |CancelWait(wait_id)| may only be called on the same thread as the
  19 //     |AsyncWait()| that provided |wait_id| was called on.
  20 //   - A given |MojoAsyncWaiter|'s functions may only be called on the thread(s)
  21 //     that it is defined to be valid on (typically including the thread on
  22 //     which the |MojoAsyncWaiter| was provided). E.g., a library may require
  23 //     initialization with a single |MojoAsyncWaiter| and stipulate that it only
  24 //     be used on threads on which that |MojoAsyncWaiter| is valid.
  25 //   - If a |MojoAsyncWaiter| is valid on multiple threads, then its functions
  26 //     must be thread-safe (subject to the first restriction above).
  27 struct MojoAsyncWaiter {
  28   // Arranges for |callback| to be called on the current thread at some future
  29   // when |handle| satisfies |signals| or it is known that it will never satisfy
  30   // |signals| (with the same behavior as |MojoWait()|).
  31   //
  32   // |callback| will not be called in the nested context of |AsyncWait()|, but
  33   // only, e.g., from some run loop. |callback| is provided with the |closure|
  34   // argument as well as the result of the wait. For each call to |AsyncWait()|,
  35   // |callback| will be called at most once.
  36   //
  37   // |handle| must not be closed or transferred (via |MojoWriteMessage()|; this
  38   // is equivalent to closing the handle) until either the callback has been
  39   // executed or the async wait has been cancelled using the returned (nonzero)
  40   // |MojoAsyncWaitID| (see |CancelWait()|). Otherwise, an invalid (or, worse,
  41   // re-used) handle may be waited on by the implementation of this
  42   // |MojoAsyncWaiter|.
  43   //
  44   // Note that once the callback has been called, the returned |MojoAsyncWaitID|
  45   // becomes invalid.
  46   MojoAsyncWaitID (*AsyncWait)(MojoHandle handle,
  47                                MojoHandleSignals signals,
  48                                MojoDeadline deadline,
  49                                MojoAsyncWaitCallback callback,
  50                                void* closure);
  51
  52   // Cancels an outstanding async wait (specified by |wait_id|) initiated by
  53   // |AsyncWait()|. This may only be called from the same thread on which the
  54   // corresponding |AsyncWait()| was called, and may only be called if the
  55   // callback to |AsyncWait()| has not been called.
  56   //
  57   // Once this has been called, the callback provided to |AsyncWait()| will not
  58   // be called. Moreover, it is then immediately safe to close or transfer the
  59   // handle provided to |AsyncWait()|. (I.e., the implementation of this
  60   // |MojoAsyncWaiter| will no longer wait on, or do anything else with, the
  61   // handle.)
  62   void (*CancelWait)(MojoAsyncWaitID wait_id);
  63 };
  64
  65 #endif  // MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_