OLD | NEW |
| (Empty) |
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_ | |
OLD | NEW |