Proposed API for querying information about (e.g. shared) buffers.

mojo/public/c/system/buffer.h

Index: mojo/public/c/system/buffer.h
diff --git a/mojo/public/c/system/buffer.h b/mojo/public/c/system/buffer.h
index 7c5bceca67bdcacf430bb34523b3edbbd92d4009..8aa25a5bf300789fd31999d0b64324536603d268 100644
--- a/mojo/public/c/system/buffer.h
+++ b/mojo/public/c/system/buffer.h
@@ -41,7 +41,7 @@ MOJO_STATIC_ASSERT(sizeof(MojoCreateSharedBufferOptions) == 8,
                    "MojoCreateSharedBufferOptions has wrong size");
 
 // |MojoDuplicateBufferHandleOptions|: Used to specify parameters in duplicating
-// access to a shared buffer to |MojoDuplicateBufferHandle()|.
+// access to a buffer to |MojoDuplicateBufferHandle()|.
 //   |uint32_t struct_size|: Set to the size of the
 //       |MojoDuplicateBufferHandleOptions| struct. (Used to allow for future
 //       extensions.)
@@ -56,13 +56,34 @@ typedef uint32_t MojoDuplicateBufferHandleOptionsFlags;
 #define MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE \
   ((MojoDuplicateBufferHandleOptionsFlags)0)
 
-struct MojoDuplicateBufferHandleOptions {
+struct MOJO_ALIGNAS(8) MojoDuplicateBufferHandleOptions {

[viettrungluu, 2016/03/01 20:36:20]

This is an ABI-breaking change, but luckily, no one actually creates/uses this
struct currently. Phew.

   uint32_t struct_size;
   MojoDuplicateBufferHandleOptionsFlags flags;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoDuplicateBufferHandleOptions) == 8,
                    "MojoDuplicateBufferHandleOptions has wrong size");
 
+// |MojoBufferInformation|: Used to provide information about a buffer (see
+// |MojoGetBufferInformation()|.
+//   |uint32_t struct_size|: Set to the size of the |MojoBufferInformation|
+//       struct. (Used to allow for future extensions.)
+//   |MojoBufferInformationFlags flags|: Reserved for future use.
+//   |uint64_t num_bytes|: Size of the buffer.
+//
+// TODO(vtl): Add flags to indicate writability, etc.? Also, type of buffer?
+
+typedef uint32_t MojoBufferInformationFlags;
+
+#define MOJO_BUFFER_INFORMATION_FLAG_NONE ((MojoBufferInformationFlags)0)
+
+struct MOJO_ALIGNAS(8) MojoBufferInformation {
+  uint32_t struct_size;
+  MojoBufferInformationFlags flags;
+  uint64_t num_bytes;
+};
+MOJO_STATIC_ASSERT(sizeof(MojoBufferInformation) == 16,
+                   "MojoBufferInformation has wrong size");
+
 // |MojoMapBufferFlags|: Used to specify different modes to |MojoMapBuffer()|.
 //   |MOJO_MAP_BUFFER_FLAG_NONE| - No flags; default mode.
 
@@ -125,6 +146,23 @@ MojoResult MojoDuplicateBufferHandle(
     const struct MojoDuplicateBufferHandleOptions* options,  // Optional.
     MojoHandle* new_buffer_handle);                          // Out.
 
+// Gets information about the buffer with handle |buffer_handle|. |info| should
+// be non-null and point to a buffer of size |info_num_bytes|; |info_num_bytes|
+// should be at least the size of |struct MojoBufferInformation| (if/when the
+// definition of this struct is extended, sizes of previous definitions will
+// still be accepted and |*info| filled accordingly).
+//
+// On success, |*info| will be filled with information about the given buffer.
+//
+// Returns:
+//   |MOJO_RESULT_OK| on success.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
+//       |buffer_handle| is not a valid buffer handle, |*info| is null, or
+//       |info_num_bytes| is too small).

[jamesr, 2016/03/07 19:26:36]

hm, buffer too small is a MOJO_RESULT_RESOURCE_EXHAUSTED return code for
MojoReadMessage. if the implementation has a larger definition of the buffer in
mind than the caller how does the caller get access to the fields they
understand? seems impossible with this setup unless the caller guesses larger
and larger buffer sizes to allocate for MojoBufferInformation until they get
MOJO_RESULT_OK, only then to read out the fields they know

what if the caller had to populate |info->struct_size| before calling the
function and the callee populated the fields up to that size, or if the
implementation always filled up to min(sizeof(implementation's
MojoBufferInformation), |info_num_bytes|) into the passed-in struct?

[viettrungluu, 2016/03/07 20:44:22]

See the parenthetical comment in the first paragraph of the comment (this will
accept and populate according to old valid sizes).
I thought about that, but opted to not do it, since in a kernel impl it'd mean
having to read in from userspace just to get a uint32_t.
We could do that. I just wonder if, e.g., setting |info_num_bytes| to 0 (or
worse, 1; or maybe more plausibly bad, 5) is valid. Or what "filled up to"
means. (The easiest implementation would be to partially memcpy a "full" struct,
and set info->struct_size to that amount copied, but that seems a little
sketchy.)

[jamesr, 2016/03/07 21:42:35]

Do we have any definition for what "old valid sizes" are?
Aside: with this scheme it seems impossible to add fields to the struct unless
they grow the size, which means if we want to add a 4-byte value (like another
flags field or something) we need to grow the struct by 8 bytes or we wouldn't
be able to add another 4-byte value later on

Maybe an explicit version field along with documented values for the size of
each version would have been better, but it's kinda late for that now.

How about we just document what values of |info_num_bytes| we support and
populate, i.e.

16: struct_size, flags, num_bytes

then sometime in the future

24: struct_size, flags, num_bytes, alignment (or whatever) the next field is

and then say that if info_num_bytes is >= any value the implementation
understands it fills in the largest value it understands and sets that in
struct_size, otherwise if info_num_bytes is not equal to one the values the
implementation understands it returns INVALID_ARGUMENT, otherwise it fills in
that exact version.

+MojoResult MojoGetBufferInformation(MojoHandle buffer_handle,
+                                    struct MojoBufferInformation* info,  // Out.
+                                    uint32_t info_num_bytes);            // In.

[jamesr, 2016/03/07 19:26:36]

inparams before outparams?

[viettrungluu, 2016/03/07 20:44:23]

I'm following existing (arguably-bad[*]) precedent (e.g., in MojoReadMessage).

[*] Except that it'd get violated anyway, since MojoReadMessage has multiple
buffers, and having the size next to the buffer seems more desirable than
following the in-then-out order. (Though MojoReadMessage's size params are
in/out, not just in.)

[jamesr, 2016/03/07 21:42:35]

Read's params are in/out except for flags which comes at the end. blah!

the other crappy thing about this ordering is that it's 32 bit, 64 bit, then 32
bit. if it was 32/32/64 it could potentially pack better

+
 // Maps the part (at offset |offset| of length |num_bytes|) of the buffer given
 // by |buffer_handle| into memory, with options specified by |flags|. |offset +
 // num_bytes| must be less than or equal to the size of the buffer. On success,