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.nio.ByteBuffer; 8 9 /** 10 * Interface for data pipes. A data pipe is a unidirectional communication channel for unframed 11 * data. Data is unframed, but must come as (multiples of) discrete elements, of the size given at 12 * creation time. 13 */ 14 public interface DataPipe { 15 16 /** 17 * Flags for the data pipe creation operation. 18 */ 19 public static class CreateFlags extends Flags<CreateFlags> { 20 private static final int FLAG_NONE = 0; 21 private static final int FLAG_MAY_DISCARD = 1 << 0; 22 23 /** 24 * Immutable flag with not bit set. 25 */ 26 public static final CreateFlags NONE = CreateFlags.none().immutable(); 27 28 /** 29 * Dedicated constructor. 30 * 31 * @param flags initial value of the flags. 32 */ CreateFlags(int flags)33 protected CreateFlags(int flags) { 34 super(flags); 35 } 36 37 /** 38 * Change the may-discard bit of this flag. This indicates that the data pipe may discard 39 * data for whatever reason; best-effort delivery. In particular, if the capacity is 40 * reached, old data may be discard to make room for new data. 41 * 42 * @param mayDiscard the new value of the may-discard bit. 43 * @return this. 44 */ setMayDiscard(boolean mayDiscard)45 public CreateFlags setMayDiscard(boolean mayDiscard) { 46 return setFlag(FLAG_MAY_DISCARD, mayDiscard); 47 } 48 49 /** 50 * @return flags with no bit set. 51 */ none()52 public static CreateFlags none() { 53 return new CreateFlags(FLAG_NONE); 54 } 55 56 } 57 58 /** 59 * Used to specify creation parameters for a data pipe to |Core.createDataPipe()|. 60 */ 61 public static class CreateOptions { 62 63 /** 64 * Used to specify different modes of operation, see |DataPipe.CreateFlags|. 65 */ 66 private CreateFlags mFlags = CreateFlags.none(); 67 /** 68 * The size of an element, in bytes. All transactions and buffers will consist of an 69 * integral number of elements. Must be nonzero. 70 */ 71 private int mElementNumBytes; 72 /** 73 * The capacity of the data pipe, in number of bytes; must be a multiple of 74 * |element_num_bytes|. The data pipe will always be able to queue AT LEAST this much data. 75 * Set to zero to opt for a system-dependent automatically-calculated capacity (which will 76 * always be at least one element). 77 */ 78 private int mCapacityNumBytes; 79 80 /** 81 * @return the flags 82 */ getFlags()83 public CreateFlags getFlags() { 84 return mFlags; 85 } 86 87 /** 88 * @return the elementNumBytes 89 */ getElementNumBytes()90 public int getElementNumBytes() { 91 return mElementNumBytes; 92 } 93 94 /** 95 * @param elementNumBytes the elementNumBytes to set 96 */ setElementNumBytes(int elementNumBytes)97 public void setElementNumBytes(int elementNumBytes) { 98 mElementNumBytes = elementNumBytes; 99 } 100 101 /** 102 * @return the capacityNumBytes 103 */ getCapacityNumBytes()104 public int getCapacityNumBytes() { 105 return mCapacityNumBytes; 106 } 107 108 /** 109 * @param capacityNumBytes the capacityNumBytes to set 110 */ setCapacityNumBytes(int capacityNumBytes)111 public void setCapacityNumBytes(int capacityNumBytes) { 112 mCapacityNumBytes = capacityNumBytes; 113 } 114 115 } 116 117 /** 118 * Flags for the write operations on MessagePipeHandle . 119 */ 120 public static class WriteFlags extends Flags<WriteFlags> { 121 private static final int FLAG_NONE = 0; 122 private static final int FLAG_ALL_OR_NONE = 1 << 0; 123 124 /** 125 * Immutable flag with not bit set. 126 */ 127 public static final WriteFlags NONE = WriteFlags.none().immutable(); 128 129 /** 130 * Dedicated constructor. 131 * 132 * @param flags initial value of the flags. 133 */ WriteFlags(int flags)134 private WriteFlags(int flags) { 135 super(flags); 136 } 137 138 /** 139 * Change the all-or-none bit of those flags. If set, write either all the elements 140 * requested or none of them. 141 * 142 * @param allOrNone the new value of all-or-none bit. 143 * @return this. 144 */ setAllOrNone(boolean allOrNone)145 public WriteFlags setAllOrNone(boolean allOrNone) { 146 return setFlag(FLAG_ALL_OR_NONE, allOrNone); 147 } 148 149 /** 150 * @return a flag with no bit set. 151 */ none()152 public static WriteFlags none() { 153 return new WriteFlags(FLAG_NONE); 154 } 155 } 156 157 /** 158 * Flags for the read operations on MessagePipeHandle. 159 */ 160 public static class ReadFlags extends Flags<ReadFlags> { 161 private static final int FLAG_NONE = 0; 162 private static final int FLAG_ALL_OR_NONE = 1 << 0; 163 private static final int FLAG_QUERY = 1 << 2; 164 165 /** 166 * Immutable flag with not bit set. 167 */ 168 public static final ReadFlags NONE = ReadFlags.none().immutable(); 169 170 /** 171 * Dedicated constructor. 172 * 173 * @param flags initial value of the flag. 174 */ ReadFlags(int flags)175 private ReadFlags(int flags) { 176 super(flags); 177 } 178 179 /** 180 * Change the all-or-none bit of this flag. If set, read (or discard) either the requested 181 * number of elements or none. 182 * 183 * @param allOrNone the new value of the all-or-none bit. 184 * @return this. 185 */ setAllOrNone(boolean allOrNone)186 public ReadFlags setAllOrNone(boolean allOrNone) { 187 return setFlag(FLAG_ALL_OR_NONE, allOrNone); 188 } 189 190 /** 191 * Change the query bit of this flag. If set query the number of elements available to read. 192 * Mutually exclusive with |dicard| and |allOrNone| is ignored if this flag is set. 193 * 194 * @param query the new value of the query bit. 195 * @return this. 196 */ query(boolean query)197 public ReadFlags query(boolean query) { 198 return setFlag(FLAG_QUERY, query); 199 } 200 201 /** 202 * @return a flag with no bit set. 203 */ none()204 public static ReadFlags none() { 205 return new ReadFlags(FLAG_NONE); 206 } 207 208 } 209 210 /** 211 * Handle for the producer part of a data pipe. 212 */ 213 public static interface ProducerHandle extends Handle { 214 215 /** 216 * @see org.chromium.mojo.system.Handle#pass() 217 */ 218 @Override pass()219 public ProducerHandle pass(); 220 221 /** 222 * Writes the given data to the data pipe producer. |elements| points to data; the buffer 223 * must be a direct ByteBuffer and the limit should be a multiple of the data pipe's element 224 * size. If |allOrNone| is set in |flags|, either all the data will be written or none is. 225 * <p> 226 * On success, returns the amount of data that was actually written. 227 * <p> 228 * Note: If the data pipe has the "may discard" option flag (specified on creation), this 229 * will discard as much data as required to write the given data, starting with the earliest 230 * written data that has not been consumed. However, even with "may discard", if the buffer 231 * limit is greater than the data pipe's capacity (and |allOrNone| is not set), this will 232 * write the maximum amount possible (namely, the data pipe's capacity) and return that 233 * amount. It will *not* discard data from |elements|. 234 * 235 * @return number of written bytes. 236 */ writeData(ByteBuffer elements, WriteFlags flags)237 public int writeData(ByteBuffer elements, WriteFlags flags); 238 239 /** 240 * Begins a two-phase write to the data pipe producer . On success, returns a |ByteBuffer| 241 * to which the caller can write. If flags has |allOrNone| set, then the buffer capacity 242 * will be at least as large as |numBytes|, which must also be a multiple of the element 243 * size (if |allOrNone| is not set, |numBytes| is ignored and the caller must check the 244 * capacity of the buffer). 245 * <p> 246 * During a two-phase write, this handle is *not* writable. E.g., if another thread tries to 247 * write to it, it will throw a |MojoException| with code |MojoResult.BUSY|; that thread can 248 * then wait for this handle to become writable again. 249 * <p> 250 * Once the caller has finished writing data to the buffer, it should call |endWriteData()| 251 * to specify the amount written and to complete the two-phase write. 252 * <p> 253 * Note: If the data pipe has the "may discard" option flag (specified on creation) and 254 * |flags| has |allOrNone| set, this may discard some data. 255 * 256 * @return The buffer to write to. 257 */ beginWriteData(int numBytes, WriteFlags flags)258 public ByteBuffer beginWriteData(int numBytes, WriteFlags flags); 259 260 /** 261 * Ends a two-phase write to the data pipe producer that was begun by a call to 262 * |beginWriteData()| on the same handle. |numBytesWritten| should indicate the amount of 263 * data actually written; it must be less than or equal to the capacity of the buffer 264 * returned by |beginWriteData()| and must be a multiple of the element size. The buffer 265 * returned from |beginWriteData()| must have been filled with exactly |numBytesWritten| 266 * bytes of data. 267 * <p> 268 * On failure, the two-phase write (if any) is ended (so the handle may become writable 269 * again, if there's space available) but no data written to the buffer is "put into" the 270 * data pipe. 271 */ endWriteData(int numBytesWritten)272 public void endWriteData(int numBytesWritten); 273 } 274 275 /** 276 * Handle for the consumer part of a data pipe. 277 */ 278 public static interface ConsumerHandle extends Handle { 279 280 /** 281 * @see org.chromium.mojo.system.Handle#pass() 282 */ 283 @Override pass()284 public ConsumerHandle pass(); 285 286 /** 287 * Discards data on the data pie consumer. This method discards up to |numBytes| (which 288 * again be a multiple of the element size) bytes of data, returning the amount actually 289 * discarded. if |flags| has |allOrNone|, it will either discard exactly |numBytes| bytes of 290 * data or none. In this case, |query| must not be set. 291 */ discardData(int numBytes, ReadFlags flags)292 public int discardData(int numBytes, ReadFlags flags); 293 294 /** 295 * Reads data from the data pipe consumer. May also be used to query the amount of data 296 * available. If |flags| has not |query| set, this tries to read up to |elements| capacity 297 * (which must be a multiple of the data pipe's element size) bytes of data to |elements| 298 * and returns the amount actually read. |elements| must be a direct ByteBuffer. If flags 299 * has |allOrNone| set, it will either read exactly |elements| capacity bytes of data or 300 * none. 301 * <p> 302 * If flags has |query| set, it queries the amount of data available, returning the number 303 * of bytes available. In this case |allOrNone| is ignored, as are |elements|. 304 */ readData(ByteBuffer elements, ReadFlags flags)305 public int readData(ByteBuffer elements, ReadFlags flags); 306 307 /** 308 * Begins a two-phase read from the data pipe consumer. On success, returns a |ByteBuffer| 309 * from which the caller can read up to its limit bytes of data. If flags has |allOrNone| 310 * set, then the limit will be at least as large as |numBytes|, which must also be a 311 * multiple of the element size (if |allOrNone| is not set, |numBytes| is ignored). |flags| 312 * must not have |query| set. 313 * <p> 314 * During a two-phase read, this handle is *not* readable. E.g., if another thread tries to 315 * read from it, it will throw a |MojoException| with code |MojoResult.BUSY|; that thread 316 * can then wait for this handle to become readable again. 317 * <p> 318 * Once the caller has finished reading data from the buffer, it should call |endReadData()| 319 * to specify the amount read and to complete the two-phase read. 320 */ beginReadData(int numBytes, ReadFlags flags)321 public ByteBuffer beginReadData(int numBytes, ReadFlags flags); 322 323 /** 324 * Ends a two-phase read from the data pipe consumer that was begun by a call to 325 * |beginReadData()| on the same handle. |numBytesRead| should indicate the amount of data 326 * actually read; it must be less than or equal to the limit of the buffer returned by 327 * |beginReadData()| and must be a multiple of the element size. 328 * <p> 329 * On failure, the two-phase read (if any) is ended (so the handle may become readable 330 * again) but no data is "removed" from the data pipe. 331 */ endReadData(int numBytesRead)332 public void endReadData(int numBytesRead); 333 } 334 335 } 336