1 // Copyright 2017 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_CPP_SYSTEM_WAIT_H_ 6 #define MOJO_PUBLIC_CPP_SYSTEM_WAIT_H_ 7 8 #include <stddef.h> 9 10 #include "mojo/public/c/system/trap.h" 11 #include "mojo/public/c/system/types.h" 12 #include "mojo/public/cpp/system/handle.h" 13 #include "mojo/public/cpp/system/system_export.h" 14 15 namespace mojo { 16 17 // Blocks the calling sequence, waiting for one or more signals in |signals| to 18 // be become satisfied, not-satisfied, or permanently unsatisfiable on the 19 // handle, depending on the |condition| selected. 20 // 21 // If |signals_state| is non-null, |handle| is valid, the wait is not cancelled 22 // (see return values below), the last known signaling state of |handle| is 23 // written to |*signals_state| before returning. 24 // 25 // Return values: 26 // |MOJO_RESULT_OK| if one or more signals in |signals| has been raised on 27 // |handle| with |condition| set to |MOJO_WATCH_CONDITION_SATISFIED|, or 28 // one or more signals in |signals| has been lowered on |handle| with 29 // |condition| set to |MOJO_WATCH_CONDITION_NOT_SATISFIED|. 30 // |MOJO_RESULT_FAILED_PRECONDITION| if the state of |handle| changes such 31 // that no signals in |signals| can ever be raised again and |condition| 32 // is |MOJO_WATCH_CONDITION_SATISFIED|. 33 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle. 34 // |MOJO_RESULT_CANCELLED| if the wait was cancelled because |handle| was 35 // closed by some other sequence while waiting. 36 MOJO_CPP_SYSTEM_EXPORT MojoResult 37 Wait(Handle handle, 38 MojoHandleSignals signals, 39 MojoTriggerCondition condition, 40 MojoHandleSignalsState* signals_state = nullptr); 41 42 // A pseudonym for the above Wait() which always waits on 43 // |MOJO_TRIGGER_CONDITION_SIGNALS_SATISFIED|. 44 inline MojoResult Wait(Handle handle, 45 MojoHandleSignals signals, 46 MojoHandleSignalsState* signals_state = nullptr) { 47 return Wait(handle, signals, MOJO_TRIGGER_CONDITION_SIGNALS_SATISFIED, 48 signals_state); 49 } 50 51 // Waits on |handles[0]|, ..., |handles[num_handles-1]| until: 52 // - At least one handle satisfies a signal indicated in its respective 53 // |signals[0]|, ..., |signals[num_handles-1]|. 54 // - It becomes known that no signal in some |signals[i]| will ever be 55 // satisfied. 56 // 57 // This means that |WaitMany()| behaves as if |Wait()| were called on each 58 // handle/signals pair simultaneously, completing when the first |Wait()| would 59 // complete. 60 // 61 // If |signals_states| is non-null, all other arguments are valid, and the wait 62 // is not cancelled (see return values below), the last known signaling state of 63 // each Handle |handles[i]| is written to its corresponding entry in 64 // |signals_states[i]| before returning. 65 // 66 // Returns values: 67 // |MOJO_RESULT_OK| if one of the Handles in |handles| had one or more of its 68 // correpsonding signals satisfied. |*result_index| contains the index 69 // of the Handle in question if |result_index| is non-null. 70 // |MOJO_RESULT_FAILED_PRECONDITION| if one of the Handles in |handles| 71 // changes state such that its corresponding signals become permanently 72 // unsatisfiable. |*result_index| contains the index of the handle in 73 // question if |result_index| is non-null. 74 // |MOJO_RESULT_INVALID_ARGUMENT| if any Handle in |handles| is invalid, 75 // or if either |handles| or |signals| is null. 76 // |MOJO_RESULT_CANCELLED| if the wait was cancelled because a handle in 77 // |handles| was closed by some other sequence while waiting. 78 // |*result_index| contains the index of the closed Handle if 79 // |result_index| is non-null. 80 MOJO_CPP_SYSTEM_EXPORT MojoResult 81 WaitMany(const Handle* handles, 82 const MojoHandleSignals* signals, 83 size_t num_handles, 84 size_t* result_index = nullptr, 85 MojoHandleSignalsState* signals_states = nullptr); 86 87 } // namespace mojo 88 89 #endif // MOJO_PUBLIC_CPP_SYSTEM_WAIT_H_ 90