Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(228)

Side by Side Diff: mojo/public/c/system/data_pipe.h

Issue 1425473003: Get rid of system_export.h, etc. (Closed) Base URL: https://github.com/domokit/mojo.git@master
Patch Set: Created 5 years, 2 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
1 // Copyright 2014 The Chromium Authors. All rights reserved. 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 2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file. 3 // found in the LICENSE file.
4 4
5 // This file contains types/constants and functions specific to data pipes. 5 // This file contains types/constants and functions specific to data pipes.
6 // 6 //
7 // Note: This header should be compilable as C. 7 // Note: This header should be compilable as C.
8 8
9 #ifndef MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ 9 #ifndef MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_
10 #define MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ 10 #define MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_
11 11
12 #include "mojo/public/c/system/macros.h" 12 #include "mojo/public/c/system/macros.h"
13 #include "mojo/public/c/system/system_export.h"
14 #include "mojo/public/c/system/types.h" 13 #include "mojo/public/c/system/types.h"
15 14
16 // |MojoCreateDataPipeOptions|: Used to specify creation parameters for a data 15 // |MojoCreateDataPipeOptions|: Used to specify creation parameters for a data
17 // pipe to |MojoCreateDataPipe()|. 16 // pipe to |MojoCreateDataPipe()|.
18 // |uint32_t struct_size|: Set to the size of the |MojoCreateDataPipeOptions| 17 // |uint32_t struct_size|: Set to the size of the |MojoCreateDataPipeOptions|
19 // struct. (Used to allow for future extensions.) 18 // struct. (Used to allow for future extensions.)
20 // |MojoCreateDataPipeOptionsFlags flags|: Used to specify different modes of 19 // |MojoCreateDataPipeOptionsFlags flags|: Used to specify different modes of
21 // operation. 20 // operation.
22 // |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. 21 // |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode.
23 // |uint32_t element_num_bytes|: The size of an element, in bytes. All 22 // |uint32_t element_num_bytes|: The size of an element, in bytes. All
(...skipping 94 matching lines...) Expand 10 before | Expand all | Expand 10 after
118 // consumer. (On failure, they are not modified.) 117 // consumer. (On failure, they are not modified.)
119 // 118 //
120 // Returns: 119 // Returns:
121 // |MOJO_RESULT_OK| on success. 120 // |MOJO_RESULT_OK| on success.
122 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 121 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
123 // |*options| is invalid). 122 // |*options| is invalid).
124 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has 123 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
125 // been reached (e.g., if the requested capacity was too large, or if the 124 // been reached (e.g., if the requested capacity was too large, or if the
126 // maximum number of handles was exceeded). 125 // maximum number of handles was exceeded).
127 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. 126 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
128 MOJO_SYSTEM_EXPORT MojoResult MojoCreateDataPipe( 127 MojoResult MojoCreateDataPipe(
129 const struct MojoCreateDataPipeOptions* options, // Optional. 128 const struct MojoCreateDataPipeOptions* options, // Optional.
130 MojoHandle* data_pipe_producer_handle, // Out. 129 MojoHandle* data_pipe_producer_handle, // Out.
131 MojoHandle* data_pipe_consumer_handle); // Out. 130 MojoHandle* data_pipe_consumer_handle); // Out.
132 131
133 // Writes the given data to the data pipe producer given by 132 // Writes the given data to the data pipe producer given by
134 // |data_pipe_producer_handle|. |elements| points to data of size |*num_bytes|; 133 // |data_pipe_producer_handle|. |elements| points to data of size |*num_bytes|;
135 // |*num_bytes| should be a multiple of the data pipe's element size. If 134 // |*num_bytes| should be a multiple of the data pipe's element size. If
136 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is set in |flags|, either all the data 135 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is set in |flags|, either all the data
137 // will be written or none is. 136 // will be written or none is.
138 // 137 //
(...skipping 12 matching lines...) Expand all
151 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data 150 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data
152 // (specified by |*num_bytes|) could not be written. 151 // (specified by |*num_bytes|) could not be written.
153 // |MOJO_RESULT_BUSY| if there is a two-phase write ongoing with 152 // |MOJO_RESULT_BUSY| if there is a two-phase write ongoing with
154 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been 153 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been
155 // called, but not yet the matching |MojoEndWriteData()|). 154 // called, but not yet the matching |MojoEndWriteData()|).
156 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the 155 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the
157 // consumer is still open) and |flags| does *not* have 156 // consumer is still open) and |flags| does *not* have
158 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set. 157 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set.
159 // 158 //
160 // TODO(vtl): Should there be a way of querying how much data can be written? 159 // TODO(vtl): Should there be a way of querying how much data can be written?
161 MOJO_SYSTEM_EXPORT MojoResult 160 MojoResult MojoWriteData(MojoHandle data_pipe_producer_handle,
162 MojoWriteData(MojoHandle data_pipe_producer_handle, 161 const void* elements,
163 const void* elements, 162 uint32_t* num_bytes, // In/out.
164 uint32_t* num_bytes, // In/out. 163 MojoWriteDataFlags flags);
165 MojoWriteDataFlags flags);
166 164
167 // Begins a two-phase write to the data pipe producer given by 165 // Begins a two-phase write to the data pipe producer given by
168 // |data_pipe_producer_handle|. On success, |*buffer| will be a pointer to which 166 // |data_pipe_producer_handle|. On success, |*buffer| will be a pointer to which
169 // the caller can write |*buffer_num_bytes| bytes of data. There are currently 167 // the caller can write |*buffer_num_bytes| bytes of data. There are currently
170 // no flags allowed, so |flags| should be |MOJO_WRITE_DATA_FLAG_NONE|. 168 // no flags allowed, so |flags| should be |MOJO_WRITE_DATA_FLAG_NONE|.
171 // 169 //
172 // During a two-phase write, |data_pipe_producer_handle| is *not* writable. 170 // During a two-phase write, |data_pipe_producer_handle| is *not* writable.
173 // E.g., if another thread tries to write to it, it will get |MOJO_RESULT_BUSY|; 171 // E.g., if another thread tries to write to it, it will get |MOJO_RESULT_BUSY|;
174 // that thread can then wait for |data_pipe_producer_handle| to become writable 172 // that thread can then wait for |data_pipe_producer_handle| to become writable
175 // again. 173 // again.
176 // 174 //
177 // When |MojoBeginWriteData()| returns |MOJO_RESULT_OK|, and the caller has 175 // When |MojoBeginWriteData()| returns |MOJO_RESULT_OK|, and the caller has
178 // finished writing data to |*buffer|, it should call |MojoEndWriteData()| to 176 // finished writing data to |*buffer|, it should call |MojoEndWriteData()| to
179 // specify the amount written and to complete the two-phase write. 177 // specify the amount written and to complete the two-phase write.
180 // |MojoEndWriteData()| need not be called for other return values. 178 // |MojoEndWriteData()| need not be called for other return values.
181 // 179 //
182 // Returns: 180 // Returns:
183 // |MOJO_RESULT_OK| on success. 181 // |MOJO_RESULT_OK| on success.
184 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 182 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
185 // |data_pipe_producer_handle| is not a handle to a data pipe producer or 183 // |data_pipe_producer_handle| is not a handle to a data pipe producer or
186 // flags has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set). 184 // flags has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set).
187 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been 185 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been
188 // closed. 186 // closed.
189 // |MOJO_RESULT_BUSY| if there is already a two-phase write ongoing with 187 // |MOJO_RESULT_BUSY| if there is already a two-phase write ongoing with
190 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been 188 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been
191 // called, but not yet the matching |MojoEndWriteData()|). 189 // called, but not yet the matching |MojoEndWriteData()|).
192 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the 190 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the
193 // consumer is still open). 191 // consumer is still open).
194 MOJO_SYSTEM_EXPORT MojoResult 192 MojoResult MojoBeginWriteData(MojoHandle data_pipe_producer_handle,
195 MojoBeginWriteData(MojoHandle data_pipe_producer_handle, 193 void** buffer, // Out.
196 void** buffer, // Out. 194 uint32_t* buffer_num_bytes, // Out.
197 uint32_t* buffer_num_bytes, // Out. 195 MojoWriteDataFlags flags);
198 MojoWriteDataFlags flags);
199 196
200 // Ends a two-phase write to the data pipe producer given by 197 // Ends a two-phase write to the data pipe producer given by
201 // |data_pipe_producer_handle| that was begun by a call to 198 // |data_pipe_producer_handle| that was begun by a call to
202 // |MojoBeginWriteData()| on the same handle. |num_bytes_written| should 199 // |MojoBeginWriteData()| on the same handle. |num_bytes_written| should
203 // indicate the amount of data actually written; it must be less than or equal 200 // indicate the amount of data actually written; it must be less than or equal
204 // to the value of |*buffer_num_bytes| output by |MojoBeginWriteData()| and must 201 // to the value of |*buffer_num_bytes| output by |MojoBeginWriteData()| and must
205 // be a multiple of the element size. The buffer given by |*buffer| from 202 // be a multiple of the element size. The buffer given by |*buffer| from
206 // |MojoBeginWriteData()| must have been filled with exactly |num_bytes_written| 203 // |MojoBeginWriteData()| must have been filled with exactly |num_bytes_written|
207 // bytes of data. 204 // bytes of data.
208 // 205 //
209 // On failure, the two-phase write (if any) is ended (so the handle may become 206 // On failure, the two-phase write (if any) is ended (so the handle may become
210 // writable again, if there's space available) but no data written to |*buffer| 207 // writable again, if there's space available) but no data written to |*buffer|
211 // is "put into" the data pipe. 208 // is "put into" the data pipe.
212 // 209 //
213 // Returns: 210 // Returns:
214 // |MOJO_RESULT_OK| on success. 211 // |MOJO_RESULT_OK| on success.
215 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 212 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
216 // |data_pipe_producer_handle| is not a handle to a data pipe producer or 213 // |data_pipe_producer_handle| is not a handle to a data pipe producer or
217 // |num_bytes_written| is invalid (greater than the maximum value provided 214 // |num_bytes_written| is invalid (greater than the maximum value provided
218 // by |MojoBeginWriteData()| or not a multiple of the element size). 215 // by |MojoBeginWriteData()| or not a multiple of the element size).
219 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer is not in a 216 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer is not in a
220 // two-phase write (e.g., |MojoBeginWriteData()| was not called or 217 // two-phase write (e.g., |MojoBeginWriteData()| was not called or
221 // |MojoEndWriteData()| has already been called). 218 // |MojoEndWriteData()| has already been called).
222 MOJO_SYSTEM_EXPORT MojoResult 219 MojoResult MojoEndWriteData(MojoHandle data_pipe_producer_handle,
223 MojoEndWriteData(MojoHandle data_pipe_producer_handle, 220 uint32_t num_bytes_written);
224 uint32_t num_bytes_written);
225 221
226 // Reads data from the data pipe consumer given by |data_pipe_consumer_handle|. 222 // Reads data from the data pipe consumer given by |data_pipe_consumer_handle|.
227 // May also be used to discard data or query the amount of data available. 223 // May also be used to discard data or query the amount of data available.
228 // 224 //
229 // If |flags| has neither |MOJO_READ_DATA_FLAG_DISCARD| nor 225 // If |flags| has neither |MOJO_READ_DATA_FLAG_DISCARD| nor
230 // |MOJO_READ_DATA_FLAG_QUERY| set, this tries to read up to |*num_bytes| (which 226 // |MOJO_READ_DATA_FLAG_QUERY| set, this tries to read up to |*num_bytes| (which
231 // must be a multiple of the data pipe's element size) bytes of data to 227 // must be a multiple of the data pipe's element size) bytes of data to
232 // |elements| and set |*num_bytes| to the amount actually read. If flags has 228 // |elements| and set |*num_bytes| to the amount actually read. If flags has
233 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, it will either read exactly 229 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, it will either read exactly
234 // |*num_bytes| bytes of data or none. Additionally, if flags has 230 // |*num_bytes| bytes of data or none. Additionally, if flags has
(...skipping 25 matching lines...) Expand all
260 // be read or discarded. 256 // be read or discarded.
261 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| 257 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE|
262 // set and the required amount of data is not available to be read or 258 // set and the required amount of data is not available to be read or
263 // discarded (and the producer is still open). 259 // discarded (and the producer is still open).
264 // |MOJO_RESULT_BUSY| if there is a two-phase read ongoing with 260 // |MOJO_RESULT_BUSY| if there is a two-phase read ongoing with
265 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been 261 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been
266 // called, but not yet the matching |MojoEndReadData()|). 262 // called, but not yet the matching |MojoEndReadData()|).
267 // |MOJO_RESULT_SHOULD_WAIT| if there is no data to be read or discarded (and 263 // |MOJO_RESULT_SHOULD_WAIT| if there is no data to be read or discarded (and
268 // the producer is still open) and |flags| does *not* have 264 // the producer is still open) and |flags| does *not* have
269 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set. 265 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set.
270 MOJO_SYSTEM_EXPORT MojoResult MojoReadData(MojoHandle data_pipe_consumer_handle, 266 MojoResult MojoReadData(MojoHandle data_pipe_consumer_handle,
271 void* elements, // Out. 267 void* elements, // Out.
272 uint32_t* num_bytes, // In/out. 268 uint32_t* num_bytes, // In/out.
273 MojoReadDataFlags flags); 269 MojoReadDataFlags flags);
274 270
275 // Begins a two-phase read from the data pipe consumer given by 271 // Begins a two-phase read from the data pipe consumer given by
276 // |data_pipe_consumer_handle|. On success, |*buffer| will be a pointer from 272 // |data_pipe_consumer_handle|. On success, |*buffer| will be a pointer from
277 // which the caller can read |*buffer_num_bytes| bytes of data. There are 273 // which the caller can read |*buffer_num_bytes| bytes of data. There are
278 // currently no valid flags, so |flags| must be |MOJO_READ_DATA_FLAG_NONE|. 274 // currently no valid flags, so |flags| must be |MOJO_READ_DATA_FLAG_NONE|.
279 // 275 //
280 // During a two-phase read, |data_pipe_consumer_handle| is *not* readable. 276 // During a two-phase read, |data_pipe_consumer_handle| is *not* readable.
281 // E.g., if another thread tries to read from it, it will get 277 // E.g., if another thread tries to read from it, it will get
282 // |MOJO_RESULT_BUSY|; that thread can then wait for |data_pipe_consumer_handle| 278 // |MOJO_RESULT_BUSY|; that thread can then wait for |data_pipe_consumer_handle|
283 // to become readable again. 279 // to become readable again.
284 // 280 //
285 // Once the caller has finished reading data from |*buffer|, it should call 281 // Once the caller has finished reading data from |*buffer|, it should call
286 // |MojoEndReadData()| to specify the amount read and to complete the two-phase 282 // |MojoEndReadData()| to specify the amount read and to complete the two-phase
287 // read. 283 // read.
288 // 284 //
289 // Returns: 285 // Returns:
290 // |MOJO_RESULT_OK| on success. 286 // |MOJO_RESULT_OK| on success.
291 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 287 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
292 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer, 288 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer,
293 // or |flags| has invalid flags set). 289 // or |flags| has invalid flags set).
294 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been 290 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been
295 // closed. 291 // closed.
296 // |MOJO_RESULT_BUSY| if there is already a two-phase read ongoing with 292 // |MOJO_RESULT_BUSY| if there is already a two-phase read ongoing with
297 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been 293 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been
298 // called, but not yet the matching |MojoEndReadData()|). 294 // called, but not yet the matching |MojoEndReadData()|).
299 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be read (and the 295 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be read (and the
300 // producer is still open). 296 // producer is still open).
301 MOJO_SYSTEM_EXPORT MojoResult 297 MojoResult MojoBeginReadData(MojoHandle data_pipe_consumer_handle,
302 MojoBeginReadData(MojoHandle data_pipe_consumer_handle, 298 const void** buffer, // Out.
303 const void** buffer, // Out. 299 uint32_t* buffer_num_bytes, // Out.
304 uint32_t* buffer_num_bytes, // Out. 300 MojoReadDataFlags flags);
305 MojoReadDataFlags flags);
306 301
307 // Ends a two-phase read from the data pipe consumer given by 302 // Ends a two-phase read from the data pipe consumer given by
308 // |data_pipe_consumer_handle| that was begun by a call to |MojoBeginReadData()| 303 // |data_pipe_consumer_handle| that was begun by a call to |MojoBeginReadData()|
309 // on the same handle. |num_bytes_read| should indicate the amount of data 304 // on the same handle. |num_bytes_read| should indicate the amount of data
310 // actually read; it must be less than or equal to the value of 305 // actually read; it must be less than or equal to the value of
311 // |*buffer_num_bytes| output by |MojoBeginReadData()| and must be a multiple of 306 // |*buffer_num_bytes| output by |MojoBeginReadData()| and must be a multiple of
312 // the element size. 307 // the element size.
313 // 308 //
314 // On failure, the two-phase read (if any) is ended (so the handle may become 309 // On failure, the two-phase read (if any) is ended (so the handle may become
315 // readable again) but no data is "removed" from the data pipe. 310 // readable again) but no data is "removed" from the data pipe.
316 // 311 //
317 // Returns: 312 // Returns:
318 // |MOJO_RESULT_OK| on success. 313 // |MOJO_RESULT_OK| on success.
319 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 314 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
320 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer or 315 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer or
321 // |num_bytes_written| is greater than the maximum value provided by 316 // |num_bytes_written| is greater than the maximum value provided by
322 // |MojoBeginReadData()| or not a multiple of the element size). 317 // |MojoBeginReadData()| or not a multiple of the element size).
323 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer is not in a 318 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer is not in a
324 // two-phase read (e.g., |MojoBeginReadData()| was not called or 319 // two-phase read (e.g., |MojoBeginReadData()| was not called or
325 // |MojoEndReadData()| has already been called). 320 // |MojoEndReadData()| has already been called).
326 MOJO_SYSTEM_EXPORT MojoResult 321 MojoResult MojoEndReadData(MojoHandle data_pipe_consumer_handle,
327 MojoEndReadData(MojoHandle data_pipe_consumer_handle, uint32_t num_bytes_read); 322 uint32_t num_bytes_read);
328 323
329 #ifdef __cplusplus 324 #ifdef __cplusplus
330 } // extern "C" 325 } // extern "C"
331 #endif 326 #endif
332 327
333 #endif // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ 328 #endif // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698