Home | History | Annotate | Download | only in system 
      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         public 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         private static final int FLAG_PEER_CLOSED = 1 << 2;
     37 
     38         /**
     39          * Immutable signals.
     40          */
     41         public static final HandleSignals NONE = HandleSignals.none().immutable();
     42         public static final HandleSignals READABLE =
     43                 HandleSignals.none().setReadable(true).immutable();
     44         public static final HandleSignals WRITABLE =
     45                 HandleSignals.none().setWritable(true).immutable();
     46 
     47         /**
     48          * Change the readable bit of this signal.
     49          *
     50          * @param readable the new value of the readable bit.
     51          * @return this.
     52          */
     53         public HandleSignals setReadable(boolean readable) {
     54             return setFlag(FLAG_READABLE, readable);
     55         }
     56 
     57         /**
     58          * Change the writable bit of this signal.
     59          *
     60          * @param writable the new value of the writable bit.
     61          * @return this.
     62          */
     63         public HandleSignals setWritable(boolean writable) {
     64             return setFlag(FLAG_WRITABLE, writable);
     65         }
     66 
     67         /**
     68          * Change the peer closed bit of this signal.
     69          *
     70          * @param peerClosed the new value of the peer closed bit.
     71          * @return this.
     72          */
     73         public HandleSignals setPeerClosed(boolean peerClosed) {
     74             return setFlag(FLAG_PEER_CLOSED, peerClosed);
     75         }
     76 
     77         /**
     78          * Returns a signal with no bit set.
     79          */
     80         public static HandleSignals none() {
     81             return new HandleSignals(FLAG_NONE);
     82         }
     83 
     84     }
     85 
     86     /**
     87      * Returns a platform-dependent monotonically increasing tick count representing "right now."
     88      */
     89     public long getTimeTicksNow();
     90 
     91     /**
     92      * Returned by wait functions to indicate the signaling state of handles.
     93      */
     94     public static class HandleSignalsState {
     95         /**
     96          * Signals that were satisfied at some time // before the call returned.
     97          */
     98         private final HandleSignals mSatisfiedSignals;
     99 
    100         /**
    101          * Signals that are possible to satisfy. For example, if the return value was
    102          * |MOJO_RESULT_FAILED_PRECONDITION|, you can use this field to determine which, if any, of
    103          * the signals can still be satisfied.
    104          */
    105         private final HandleSignals mSatisfiableSignals;
    106 
    107         /**
    108          * Constructor.
    109          */
    110         public HandleSignalsState(
    111                 HandleSignals satisfiedSignals, HandleSignals satisfiableSignals) {
    112             mSatisfiedSignals = satisfiedSignals;
    113             mSatisfiableSignals = satisfiableSignals;
    114         }
    115 
    116         /**
    117          * Returns the satisfiedSignals.
    118          */
    119         public HandleSignals getSatisfiedSignals() {
    120             return mSatisfiedSignals;
    121         }
    122 
    123         /**
    124          * Returns the satisfiableSignals.
    125          */
    126         public HandleSignals getSatisfiableSignals() {
    127             return mSatisfiableSignals;
    128         }
    129     }
    130 
    131     /**
    132      * Result for the |wait| method.
    133      */
    134     public static class WaitResult {
    135         /**
    136          * The result of the wait method.
    137          * <p>
    138          * |MojoResult.OK| if some signal in |signals| was satisfied (or is already satisfied).
    139          * <p>
    140          * |MojoResult.DEADLINE_EXCEEDED| if the deadline has passed without any of the signals
    141          * being satisfied.
    142          * <p>
    143          * |MojoResult.CANCELLED| if |handle| is closed concurrently by another thread.
    144          * <p>
    145          * |MojoResult.FAILED_PRECONDITION| if it is or becomes impossible that any flag in
    146          * |signals| will ever be satisfied (for example, if the other endpoint is closed).
    147          */
    148         private int mMojoResult;
    149 
    150         /**
    151          * The signaling state of handles.
    152          */
    153         private HandleSignalsState mHandleSignalsState;
    154 
    155         /**
    156          * Returns the mojoResult.
    157          */
    158         public int getMojoResult() {
    159             return mMojoResult;
    160         }
    161 
    162         /**
    163          * @param mojoResult the mojoResult to set
    164          */
    165         public void setMojoResult(int mojoResult) {
    166             mMojoResult = mojoResult;
    167         }
    168 
    169         /**
    170          * Returns the handleSignalsState.
    171          */
    172         public HandleSignalsState getHandleSignalsState() {
    173             return mHandleSignalsState;
    174         }
    175 
    176         /**
    177          * @param handleSignalsState the handleSignalsState to set
    178          */
    179         public void setHandleSignalsState(HandleSignalsState handleSignalsState) {
    180             mHandleSignalsState = handleSignalsState;
    181         }
    182     }
    183 
    184     /**
    185      * Waits on the given |handle| until the state indicated by |signals| is satisfied or until
    186      * |deadline| has passed.
    187      *
    188      * @return a |WaitResult|.
    189      */
    190     public WaitResult wait(Handle handle, HandleSignals signals, long deadline);
    191 
    192     /**
    193      * Result for the |waitMany| method.
    194      */
    195     public static class WaitManyResult {
    196 
    197         /**
    198          * See |wait| for the different possible values.
    199          */
    200         private int mMojoResult;
    201 
    202         /**
    203          * If |mojoResult| is |MojoResult.OK|, |handleIndex| is the index of the handle for which
    204          * some flag was satisfied (or is already satisfied). If |mojoResult| is
    205          * |MojoResult.CANCELLED| or |MojoResult.FAILED_PRECONDITION|, |handleIndex| is the index of
    206          * the handle for which the issue occurred.
    207          */
    208         private int mHandleIndex;
    209 
    210         /**
    211          * The signaling state of handles. Will not be set if |mojoResult| is
    212          * |MOJO_RESULT_INVALID_ARGUMENT| or |MOJO_RESULT_RESOURCE_EXHAUSTED|
    213          */
    214         private List<HandleSignalsState> mSignalStates;
    215 
    216         /**
    217          * Returns the mojoResult.
    218          */
    219         public int getMojoResult() {
    220             return mMojoResult;
    221         }
    222 
    223         /**
    224          * @param mojoResult the mojoResult to set
    225          */
    226         public void setMojoResult(int mojoResult) {
    227             mMojoResult = mojoResult;
    228         }
    229 
    230         /**
    231          * Returns the handleIndex.
    232          */
    233         public int getHandleIndex() {
    234             return mHandleIndex;
    235         }
    236 
    237         /**
    238          * @param handleIndex the handleIndex to set
    239          */
    240         public void setHandleIndex(int handleIndex) {
    241             mHandleIndex = handleIndex;
    242         }
    243 
    244         /**
    245          * Returns the signalStates.
    246          */
    247         public List<HandleSignalsState> getSignalStates() {
    248             return mSignalStates;
    249         }
    250 
    251         /**
    252          * @param signalStates the signalStates to set
    253          */
    254         public void setSignalStates(List<HandleSignalsState> signalStates) {
    255             mSignalStates = signalStates;
    256         }
    257     }
    258 
    259     /**
    260      * Waits on handle in |handles| for at least one of them to satisfy the associated
    261      * |HandleSignals|, or until |deadline| has passed.
    262      *
    263      * @returns a |WaitManyResult|.
    264      */
    265     public WaitManyResult waitMany(List<Pair<Handle, HandleSignals>> handles, long deadline);
    266 
    267     /**
    268      * Creates a message pipe, which is a bidirectional communication channel for framed data (i.e.,
    269      * messages), with the given options. Messages can contain plain data and/or Mojo handles.
    270      *
    271      * @return the set of handles for the two endpoints (ports) of the message pipe.
    272      */
    273     public Pair<MessagePipeHandle, MessagePipeHandle> createMessagePipe(
    274             MessagePipeHandle.CreateOptions options);
    275 
    276     /**
    277      * Creates a data pipe, which is a unidirectional communication channel for unframed data, with
    278      * the given options. Data is unframed, but must come as (multiples of) discrete elements, of
    279      * the size given in |options|. See |DataPipe.CreateOptions| for a description of the different
    280      * options available for data pipes. |options| may be set to null for a data pipe with the
    281      * default options (which will have an element size of one byte and have some system-dependent
    282      * capacity).
    283      *
    284      * @return the set of handles for the two endpoints of the data pipe.
    285      */
    286     public Pair<DataPipe.ProducerHandle, DataPipe.ConsumerHandle> createDataPipe(
    287             DataPipe.CreateOptions options);
    288 
    289     /**
    290      * Creates a buffer that can be shared between applications (by duplicating the handle -- see
    291      * |SharedBufferHandle.duplicate()| -- and passing it over a message pipe). To access the
    292      * buffer, one must call |SharedBufferHandle.map|.
    293      *
    294      * @return the new |SharedBufferHandle|.
    295      */
    296     public SharedBufferHandle createSharedBuffer(SharedBufferHandle.CreateOptions options,
    297             long numBytes);
    298 
    299     /**
    300      * Acquires a handle from the native side. The handle will be owned by the returned object and
    301      * must not be closed outside of it.
    302      *
    303      * @return a new {@link UntypedHandle} representing the native handle.
    304      */
    305     public UntypedHandle acquireNativeHandle(int handle);
    306 
    307     /**
    308      * Returns a default implementation of {@link AsyncWaiter}.
    309      */
    310     public AsyncWaiter getDefaultAsyncWaiter();
    311 
    312     /**
    313      * Returns a new run loop.
    314      */
    315     public RunLoop createDefaultRunLoop();
    316 
    317     /**
    318      * Returns the current run loop if it exists.
    319      */
    320     public RunLoop getCurrentRunLoop();
    321 }
    322