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 // This file contains basic functions common to different Mojo system APIs. 6 // 7 // Note: This header should be compilable as C. 8 9 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ 10 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ 11 12 // Note: This header should be compilable as C. 13 14 #include "mojo/public/c/system/system_export.h" 15 #include "mojo/public/c/system/types.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 // Note: Pointer parameters that are labelled "optional" may be null (at least 22 // under some circumstances). Non-const pointer parameters are also labeled 23 // "in", "out", or "in/out", to indicate how they are used. (Note that how/if 24 // such a parameter is used may depend on other parameters or the requested 25 // operation's success/failure. E.g., a separate |flags| parameter may control 26 // whether a given "in/out" parameter is used for input, output, or both.) 27 28 // Platform-dependent monotonically increasing tick count representing "right 29 // now." The resolution of this clock is ~1-15ms. Resolution varies depending 30 // on hardware/operating system configuration. 31 MOJO_SYSTEM_EXPORT MojoTimeTicks MojoGetTimeTicksNow(void); 32 33 // Closes the given |handle|. 34 // 35 // Returns: 36 // |MOJO_RESULT_OK| on success. 37 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle. 38 // 39 // Concurrent operations on |handle| may succeed (or fail as usual) if they 40 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if 41 // they properly overlap (this is likely the case with |MojoWait()|, etc.), or 42 // fail with |MOJO_RESULT_INVALID_ARGUMENT| if they happen after. 43 MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle); 44 45 // Waits on the given handle until a signal indicated by |signals| is satisfied, 46 // it becomes known that no signal indicated by |signals| will ever be satisfied 47 // (see the description of the |MOJO_RESULT_CANCELLED| and 48 // |MOJO_RESULT_FAILED_PRECONDITION| return values below), or until |deadline| 49 // has passed. 50 // 51 // If |deadline| is |MOJO_DEADLINE_INDEFINITE|, this will wait "forever" (until 52 // one of the other wait termination conditions is satisfied). If |deadline| is 53 // 0, this will return |MOJO_RESULT_DEADLINE_EXCEEDED| only if one of the other 54 // termination conditions (e.g., a signal is satisfied, or all signals are 55 // unsatisfiable) is not already satisfied. 56 // 57 // Returns: 58 // |MOJO_RESULT_OK| if some signal in |signals| was satisfied (or is already 59 // satisfied). 60 // |MOJO_RESULT_CANCELLED| if |handle| was closed (necessarily from another 61 // thread) during the wait. 62 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle (e.g., if 63 // it has already been closed). 64 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of 65 // the signals being satisfied. 66 // |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the 67 // signals in |signals| can ever be satisfied (e.g., when waiting on one 68 // end of a message pipe and the other end is closed). 69 // 70 // If there are multiple waiters (on different threads, obviously) waiting on 71 // the same handle and signal, and that signal becomes is satisfied, all waiters 72 // will be awoken. 73 MOJO_SYSTEM_EXPORT MojoResult MojoWait(MojoHandle handle, 74 MojoHandleSignals signals, 75 MojoDeadline deadline); 76 77 // Waits on |handles[0]|, ..., |handles[num_handles-1]| until (at least) one 78 // satisfies a signal indicated in its respective |signals[0]|, ..., 79 // |signals[num_handles-1]|, it becomes known that no signal in some 80 // |signals[i]| will ever be satisfied, or until |deadline| has passed. 81 // 82 // This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on 83 // each handle/signals pair simultaneously, completing when the first 84 // |MojoWait()| would complete. 85 // 86 // See |MojoWait()| for more details about |deadline|. 87 // 88 // Returns: 89 // The index |i| (from 0 to |num_handles-1|) if |handle[i]| satisfies a signal 90 // from |signals[i]|. 91 // |MOJO_RESULT_CANCELLED| if some |handle[i]| was closed (necessarily from 92 // another thread) during the wait. 93 // |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle 94 // (e.g., if it has already been closed). 95 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of 96 // handles satisfying any of its signals. 97 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME 98 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. 99 MOJO_SYSTEM_EXPORT MojoResult MojoWaitMany(const MojoHandle* handles, 100 const MojoHandleSignals* signals, 101 uint32_t num_handles, 102 MojoDeadline deadline); 103 104 #ifdef __cplusplus 105 } // extern "C" 106 #endif 107 108 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ 109