OLD | NEW |
1 // Copyright 2014 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_ | 5 #ifndef MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_ |
6 #define MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_ | 6 #define MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_ |
7 | 7 |
8 #include "mojo/public/c/system/types.h" | 8 #include "mojo/public/c/system/types.h" |
9 | 9 |
10 typedef uintptr_t MojoAsyncWaitID; | 10 typedef uintptr_t MojoAsyncWaitID; |
11 | 11 |
12 typedef void (*MojoAsyncWaitCallback)(void* closure, MojoResult result); | 12 typedef void (*MojoAsyncWaitCallback)(void* closure, MojoResult result); |
13 | 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 { | 14 struct MojoAsyncWaiter { |
28 // Arranges for |callback| to be called on the current thread at some future | 15 // Asynchronously call MojoWait on a background thread, and pass the result |
29 // when |handle| satisfies |signals| or it is known that it will never satisfy | 16 // of MojoWait to the given MojoAsyncWaitCallback on the current thread. |
30 // |signals| (with the same behavior as |MojoWait()|). | 17 // Returns a non-zero MojoAsyncWaitID that can be used with CancelWait to |
31 // | 18 // stop waiting. This identifier becomes invalid once the callback runs. |
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, | 19 MojoAsyncWaitID (*AsyncWait)(MojoHandle handle, |
47 MojoHandleSignals signals, | 20 MojoHandleSignals signals, |
48 MojoDeadline deadline, | 21 MojoDeadline deadline, |
49 MojoAsyncWaitCallback callback, | 22 MojoAsyncWaitCallback callback, |
50 void* closure); | 23 void* closure); |
51 | 24 |
52 // Cancels an outstanding async wait (specified by |wait_id|) initiated by | 25 // Cancel an existing call to AsyncWait with the given MojoAsyncWaitID. The |
53 // |AsyncWait()|. This may only be called from the same thread on which the | 26 // corresponding MojoAsyncWaitCallback will not be called in this case. |
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); | 27 void (*CancelWait)(MojoAsyncWaitID wait_id); |
63 }; | 28 }; |
64 | 29 |
65 #endif // MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_ | 30 #endif // MOJO_PUBLIC_C_ENVIRONMENT_ASYNC_WAITER_H_ |
OLD | NEW |