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_ 66
