Mojo: Armed Watchers

mojo/public/c/system/data_pipe.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // This file contains types/constants and functions specific to data pipes.
 //
 // Note: This header should be compilable as C.
 
 #ifndef MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_
 #define MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_
@@ skipping 38 matching lines @@
   MOJO_ALIGNAS(4) uint32_t capacity_num_bytes;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoCreateDataPipeOptions) == 16,
                    "MojoCreateDataPipeOptions has wrong size");
 
 // |MojoWriteDataFlags|: Used to specify different modes to |MojoWriteData()|
 // and |MojoBeginWriteData()|.
 //   |MOJO_WRITE_DATA_FLAG_NONE| - No flags; default mode.
 //   |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| - Write either all the elements
 //       requested or none of them.
+//   |MOJO_WRITE_DATA_FLAG_CLEAR_SIGNAL| - If writing fails due to a lack of
+//       available capacity,  clear the |MOJO_HANDLE_SIGNAL_WRITABLE| signal
+//       until more capacity becomes available.
 
 typedef uint32_t MojoWriteDataFlags;
 
 #ifdef __cplusplus
 const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_NONE = 0;
 const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_ALL_OR_NONE = 1 << 0;
+const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_CLEAR_SIGNAL = 1 << 1;
 #else
 #define MOJO_WRITE_DATA_FLAG_NONE ((MojoWriteDataFlags)0)
 #define MOJO_WRITE_DATA_FLAG_ALL_OR_NONE ((MojoWriteDataFlags)1 << 0)
+#define MOJO_WRITE_DATA_FLAG_CLEAR_SIGNAL ((MojoWriteDataFlags)1 << 1)
 #endif
 
 // |MojoReadDataFlags|: Used to specify different modes to |MojoReadData()| and
 // |MojoBeginReadData()|.
 //   |MOJO_READ_DATA_FLAG_NONE| - No flags; default mode.
 //   |MOJO_READ_DATA_FLAG_ALL_OR_NONE| - Read (or discard) either the requested
 //        number of elements or none.
 //   |MOJO_READ_DATA_FLAG_DISCARD| - Discard (up to) the requested number of
 //        elements.
 //   |MOJO_READ_DATA_FLAG_QUERY| - Query the number of elements available to
 //       read. For use with |MojoReadData()| only. Mutually exclusive with
 //       |MOJO_READ_DATA_FLAG_DISCARD|, and |MOJO_READ_DATA_FLAG_ALL_OR_NONE|
 //       is ignored if this flag is set.
 //   |MOJO_READ_DATA_FLAG_PEEK| - Read elements without removing them. For use
 //       with |MojoReadData()| only. Mutually exclusive with
 //       |MOJO_READ_DATA_FLAG_DISCARD| and |MOJO_READ_DATA_FLAG_QUERY|.
+//   |MOJO_READ_DATA_FLAG_CLEAR_SIGNAL| - If reading fails due to a lack of

[yzshen1, 2017/03/11 00:44:58]

An idea for your consideration:
One thing is that this CLEAR_SIGNAL changes the handle state that may also
affects others.

For example, pipe_user_a does read with ALL_OR_NONE | CLEAR_SIGNAL. And later it
gives the pipe to pipe_user_b. Pipe_user_b doesn't do ALL_OR_NONE, and it
decides to wait until READABLE instead of directly trying a read. In that case,
if no new data is available, pipe_user_b will never do a read, because the pipe
appears unreadable to him. 

Is it possible to define a new kind of signal? For example, NEW_DATA_READABLE.
It will signal whenever new data arrives. Anyone who wants to do ALL_OR_NONE
read should watch for NEW_DATA_READABLE instead.

WDYT?

[Ken Rockot(use gerrit already), 2017/03/12 22:24:13]

Argued with myself for a while over this. I think it's a good solution. Done (in
a separate precursor CL)

+//       available data, clear the |MOJO_HANDLE_SIGNAL_READABLE| signal until
+//       more data arrives.
 
 typedef uint32_t MojoReadDataFlags;
 
 #ifdef __cplusplus
 const MojoReadDataFlags MOJO_READ_DATA_FLAG_NONE = 0;
 const MojoReadDataFlags MOJO_READ_DATA_FLAG_ALL_OR_NONE = 1 << 0;
 const MojoReadDataFlags MOJO_READ_DATA_FLAG_DISCARD = 1 << 1;
 const MojoReadDataFlags MOJO_READ_DATA_FLAG_QUERY = 1 << 2;
 const MojoReadDataFlags MOJO_READ_DATA_FLAG_PEEK = 1 << 3;
+const MojoReadDataFlags MOJO_READ_DATA_FLAG_CLEAR_SIGNAL = 1 << 4;
 #else
 #define MOJO_READ_DATA_FLAG_NONE ((MojoReadDataFlags)0)
 #define MOJO_READ_DATA_FLAG_ALL_OR_NONE ((MojoReadDataFlags)1 << 0)
 #define MOJO_READ_DATA_FLAG_DISCARD ((MojoReadDataFlags)1 << 1)
 #define MOJO_READ_DATA_FLAG_QUERY ((MojoReadDataFlags)1 << 2)
 #define MOJO_READ_DATA_FLAG_PEEK ((MojoReadDataFlags)1 << 3)
+#define MOJO_READ_DATA_FLAG_CLEAR_SIGNAL ((MojoReadDataFlags)1 << 4)
 #endif
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 // Note: See the comment in functions.h about the meaning of the "optional"
 // label for pointer parameters.
 
 // Creates a data pipe, which is a unidirectional communication channel for
@@ skipping 250 matching lines @@
 //       |MojoEndReadData()| has already been called).
 MOJO_SYSTEM_EXPORT MojoResult
     MojoEndReadData(MojoHandle data_pipe_consumer_handle,
                     uint32_t num_bytes_read);
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_