src/mojo/public/java/system/src/org/chromium/mojo/system/Core.java

   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 package org.chromium.mojo.system;
   6
   7 import java.util.List;
   8
   9 /**
  10  * Core mojo interface giving access to the base operations. See |src/mojo/public/c/system/core.h|
  11  * for the underlying api.
  12  */
  13 public interface Core {
  14
  15     /**
  16      * Used to indicate an infinite deadline (timeout).
  17      */
  18     public static final long DEADLINE_INFINITE = -1;
  19
  20     /**
  21      * Signals for the wait operations on handles.
  22      */
  23     public static class HandleSignals extends Flags<HandleSignals> {
  24         /**
  25          * Constructor.
  26          *
  27          * @param signals the serialized signals.
  28          */
  29         private HandleSignals(int signals) {
  30             super(signals);
  31         }
  32
  33         private static final int FLAG_NONE = 0;
  34         private static final int FLAG_READABLE = 1 << 0;
  35         private static final int FLAG_WRITABLE = 1 << 1;
  36
  37         /**
  38          * Immutable signals.
  39          */
  40         public static final HandleSignals NONE = HandleSignals.none().immutable();
  41         public static final HandleSignals READABLE =
  42                 HandleSignals.none().setReadable(true).immutable();
  43         public static final HandleSignals WRITABLE =
  44                 HandleSignals.none().setWritable(true).immutable();
  45
  46         /**
  47          * Change the readable bit of this signal.
  48          *
  49          * @param readable the new value of the readable bit.
  50          * @return this.
  51          */
  52         public HandleSignals setReadable(boolean readable) {
  53             return setFlag(FLAG_READABLE, readable);
  54         }
  55
  56         /**
  57          * Change the writable bit of this signal.
  58          *
  59          * @param writable the new value of the writable bit.
  60          * @return this.
  61          */
  62         public HandleSignals setWritable(boolean writable) {
  63             return setFlag(FLAG_WRITABLE, writable);
  64         }
  65
  66         /**
  67          * @return a signal with no bit set.
  68          */
  69         public static HandleSignals none() {
  70             return new HandleSignals(FLAG_NONE);
  71         }
  72
  73     }
  74
  75     /**
  76      * @return a platform-dependent monotonically increasing tick count representing "right now."
  77      */
  78     public long getTimeTicksNow();
  79
  80     /**
  81      * Waits on the given |handle| until the state indicated by |signals| is satisfied or until
  82      * |deadline| has passed.
  83      *
  84      * @return |MojoResult.OK| if some signal in |signals| was satisfied (or is already satisfied).
  85      *         <p>
  86      *         |MojoResult.DEADLINE_EXCEEDED| if the deadline has passed without any of the signals
  87      *         being satisfied.
  88      *         <p>
  89      *         |MojoResult.CANCELLED| if |handle| is closed concurrently by another thread.
  90      *         <p>
  91      *         |MojoResult.FAILED_PRECONDITION| if it is or becomes impossible that any flag in
  92      *         |signals| will ever be satisfied (for example, if the other endpoint is close).
  93      */
  94     public int wait(Handle handle, HandleSignals signals, long deadline);
  95
  96     /**
  97      * Result for the |waitMany| method.
  98      */
  99     public static class WaitManyResult {
 100
 101         /**
 102          * See |wait| for the different possible values.
 103          */
 104         private int mMojoResult;
 105         /**
 106          * If |mojoResult| is |MojoResult.OK|, |handleIndex| is the index of the handle for which
 107          * some flag was satisfied (or is already satisfied). If |mojoResult| is
 108          * |MojoResult.CANCELLED| or |MojoResult.FAILED_PRECONDITION|, |handleIndex| is the index of
 109          * the handle for which the issue occurred.
 110          */
 111         private int mHandleIndex;
 112
 113         /**
 114          * @return the mojoResult
 115          */
 116         public int getMojoResult() {
 117             return mMojoResult;
 118         }
 119
 120         /**
 121          * @param mojoResult the mojoResult to set
 122          */
 123         public void setMojoResult(int mojoResult) {
 124             mMojoResult = mojoResult;
 125         }
 126
 127         /**
 128          * @return the handleIndex
 129          */
 130         public int getHandleIndex() {
 131             return mHandleIndex;
 132         }
 133
 134         /**
 135          * @param handleIndex the handleIndex to set
 136          */
 137         public void setHandleIndex(int handleIndex) {
 138             mHandleIndex = handleIndex;
 139         }
 140     }
 141
 142     /**
 143      * Waits on handle in |handles| for at least one of them to satisfy the associated
 144      * |HandleSignals|, or until |deadline| has passed.
 145      *
 146      * @returns a |WaitManyResult|.
 147      */
 148     public WaitManyResult waitMany(List<Pair<Handle, HandleSignals>> handles, long deadline);
 149
 150     /**
 151      * Creates a message pipe, which is a bidirectional communication channel for framed data (i.e.,
 152      * messages), with the given options. Messages can contain plain data and/or Mojo handles.
 153      *
 154      * @return the set of handles for the two endpoints (ports) of the message pipe.
 155      */
 156     public Pair<MessagePipeHandle, MessagePipeHandle> createMessagePipe(
 157             MessagePipeHandle.CreateOptions options);
 158
 159     /**
 160      * Creates a data pipe, which is a unidirectional communication channel for unframed data, with
 161      * the given options. Data is unframed, but must come as (multiples of) discrete elements, of
 162      * the size given in |options|. See |DataPipe.CreateOptions| for a description of the different
 163      * options available for data pipes. |options| may be set to null for a data pipe with the
 164      * default options (which will have an element size of one byte and have some system-dependent
 165      * capacity).
 166      *
 167      * @return the set of handles for the two endpoints of the data pipe.
 168      */
 169     public Pair<DataPipe.ProducerHandle, DataPipe.ConsumerHandle> createDataPipe(
 170             DataPipe.CreateOptions options);
 171
 172     /**
 173      * Creates a buffer that can be shared between applications (by duplicating the handle -- see
 174      * |SharedBufferHandle.duplicate()| -- and passing it over a message pipe). To access the
 175      * buffer, one must call |SharedBufferHandle.map|.
 176      *
 177      * @return the new |SharedBufferHandle|.
 178      */
 179     public SharedBufferHandle createSharedBuffer(SharedBufferHandle.CreateOptions options,
 180             long numBytes);
 181
 182     /**
 183      * Acquires a handle from the native side. The handle will be owned by the returned object and
 184      * must not be closed outside of it.
 185      *
 186      * @return a new {@link UntypedHandle} representing the native handle.
 187      */
 188     public UntypedHandle acquireNativeHandle(int handle);
 189
 190     /**
 191      * Returns a default implementation of {@link AsyncWaiter}.
 192      */
 193     public AsyncWaiter getDefaultAsyncWaiter();
 194
 195 }