mojo/public/c/system/functions.h

   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_