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
5package org.chromium.mojo.system;
6
7import 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 */
13public 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}
196