Initial in-process implementation of some Mojo primitives.

mojo/public/system/core.h

 // Copyright 2013 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.
 
 #ifndef MOJO_PUBLIC_SYSTEM_CORE_H_
 #define MOJO_PUBLIC_SYSTEM_CORE_H_
 
+// Note: This header should be compilable as C.
+
 #include <stdint.h>

[darin (slow to review), 2013/09/24 22:48:19]

This probably goes without saying:
I think on Windows, this works assuming VS2010. We can provide a dummy stdint.h
for older versions of the compiler as needed.

 
+// Types -----------------------------------------------------------------------
+
+// TODO(vtl): Notes: Use of undefined flags will lead to undefined behavior
+// (typically they'll be ignored), not necessarily an error.

[darin (slow to review), 2013/09/24 22:48:19]

I guess this is primarily an issue for newer clients running on older versions
of the system, where new flags have since been introduced. Hmm...

[viettrungluu, 2013/09/26 17:59:15]

Indeed. The reason I want to record this somewhere (probably not here) is that
this is a compatibility issue, but I don't want to incur the cost of validating
flags (even if it's admittedly a small cost).

(Possibly, it'd be safer to validate flags, though then that'd preclude, e.g.,
"waiting on everything".)

+
 typedef uint32_t MojoHandle;
 
+typedef int32_t MojoResult;
+
+typedef uint32_t MojoWaitFlags;
+
+// Used to specify deadlines in microseconds. Note that -1 means "forever".
+typedef uint64_t MojoDeadline;
+
+typedef uint32_t MojoWriteMessageFlags;
+
+typedef uint32_t MojoReadMessageFlags;
+
+// Constants -------------------------------------------------------------------
+
+// |MojoHandle|:
+#ifdef __cplusplus
+const MojoHandle MOJO_HANDLE_INVALID = 0;

[darin (slow to review), 2013/09/25 06:06:07]

yay, sanity!  i'm so glad you chose a value other than -1 for this ;-)

+#else
+#define MOJO_HANDLE_INVALID ((MojoHandle) 0)
+#endif
+
+// |MojoResult|:
+// TODO(vtl): Add documentation. The first N are equivalent to Google3 canonical
+// error codes (google3/util/task/codes.proto).
+#ifdef __cplusplus
+const MojoResult MOJO_RESULT_OK = 0;
+const MojoResult MOJO_RESULT_CANCELLED = -1;
+const MojoResult MOJO_RESULT_UNKNOWN = -2;
+const MojoResult MOJO_RESULT_INVALID_ARGUMENT = -3;
+const MojoResult MOJO_RESULT_DEADLINE_EXCEEDED = -4;
+const MojoResult MOJO_RESULT_NOT_FOUND = -5;
+const MojoResult MOJO_RESULT_ALREADY_EXISTS = -6;
+const MojoResult MOJO_RESULT_PERMISSION_DENIED = -7;
+const MojoResult MOJO_RESULT_RESOURCE_EXHAUSTED = -8;
+const MojoResult MOJO_RESULT_FAILED_PRECONDITION = -9;
+const MojoResult MOJO_RESULT_ABORTED = -10;

[darin (slow to review), 2013/09/25 06:06:07]

what is the difference between ABORTED and CANCELLED?

[viettrungluu, 2013/09/25 18:22:16]

(I plan on adding/copying documentation, but for now you can look at
http://cs/#piper///depot/google3/util/task/codes.proto .)

Cancelled is due to caller action, whereas aborted is a system action.

+const MojoResult MOJO_RESULT_OUT_OF_RANGE = -11;
+const MojoResult MOJO_RESULT_UNIMPLEMENTED = -12;
+const MojoResult MOJO_RESULT_INTERNAL = -13;

[darin (slow to review), 2013/09/25 06:06:07]

what does the INTERNAL error code refer too? my experience with the net:: error
codes is that it really helps to have individual error codes for each error
source. MOJO_RESULT_UNKNOWN would be quite a sad error code since it leaves you
with little information to help investigate a cause. we should feel free to
append new error codes as needed during implementation.

[viettrungluu, 2013/09/25 18:22:16]

"Internal" should basically never happen -- it indicates a bug in the system
itself. I agree that we should feel free to append new error codes necessary,
but at the same time try to resist error reporting that's too detailed.

(A litmus test for whether you need separate error codes might be if the caller
should do different things in response. For debugging purposes, suitable logging
may be better....)

+const MojoResult MOJO_RESULT_UNAVAILABLE = -14;
+const MojoResult MOJO_RESULT_DATA_LOSS = -15;
+#else
+#define MOJO_RESULT_OK ((MojoResult) 0)
+#define MOJO_RESULT_CANCELLED ((MojoResult) -1)
+#define MOJO_RESULT_UNKNOWN ((MojoResult) -2)
+#define MOJO_RESULT_INVALID_ARGUMENT ((MojoResult) -3)
+#define MOJO_RESULT_DEADLINE_EXCEEDED ((MojoResult) -4)
+#define MOJO_RESULT_NOT_FOUND ((MojoResult) -5)
+#define MOJO_RESULT_ALREADY_EXISTS ((MojoResult) -6)
+#define MOJO_RESULT_PERMISSION_DENIED ((MojoResult) -7)
+#define MOJO_RESULT_RESOURCE_EXHAUSTED ((MojoResult) -8)
+#define MOJO_RESULT_FAILED_PRECONDITION ((MojoResult) -9)
+#define MOJO_RESULT_ABORTED ((MojoResult) -10)
+#define MOJO_RESULT_OUT_OF_RANGE ((MojoResult) -11)
+#define MOJO_RESULT_UNIMPLEMENTED ((MojoResult) -12)
+#define MOJO_RESULT_INTERNAL ((MojoResult) -13)
+#define MOJO_RESULT_UNAVAILABLE ((MojoResult) -14)
+#define MOJO_RESULT_DATA_LOSS ((MojoResult) -15)
+#endif
+
+// |MojoWaitFlags|:
+//    MOJO_WAIT_FLAG_NONE - default flags: will wait on everything
+//    MOJO_WAIT_FLAG_READABLE - can read from the handle
+//    MOJO_WAIT_FLAG_WRITABLE - can write to the handle
+#ifdef __cplusplus
+const MojoWaitFlags MOJO_WAIT_FLAG_NONE = 0;

[darin (slow to review), 2013/09/24 22:48:19]

since MojoWaitFlags is just a typedef for an uint32_t, wouldn't you get a
similar result (type safety wise) with using an enum here? the benefit is that
an enum will work fine in C as well as C++. then, you don't have to duplicate
code. Ditto for the MOJO_RESULT_* values.

[darin (slow to review), 2013/09/25 06:06:07]

Not having to duplicate these values would be nice as it would suck for these to
be out-of-sync. Plus, even in C code, it is nice to avoid macros :-P

[viettrungluu, 2013/09/25 18:22:16]

Sigh. Maybe. enums are of unspecified width and signedness, so you could
conceivably get type-conversion or sign-conversion warnings....

Possibly I should make a macro to do the right thing and avoid the duplication.

Hrm.

[viettrungluu, 2013/09/25 19:48:00]

Blech, of course you can't have a macro to define a macro. :(

+const MojoWaitFlags MOJO_WAIT_FLAG_READABLE = 1 << 0;
+const MojoWaitFlags MOJO_WAIT_FLAG_WRITABLE = 1 << 1;
+const MojoWaitFlags MOJO_WAIT_FLAG_EVERYTHING = ~0;
+// TODO(vtl): Moar.
+#else
+#define MOJO_WAIT_FLAG_NONE ((MojoWaitFlags) 0)
+#define MOJO_WAIT_FLAG_READABLE ((MojoWaitFlags) 1 << 0)
+#define MOJO_WAIT_FLAG_WRITABLE ((MojoWaitFlags) 1 << 1)
+#define MOJO_WAIT_FLAG_EVERYTHING (~((MojoWaitFlags) 0))
+// TODO(vtl): Moar.
+#endif
+
+// |MojoDeadline|:
+#ifdef __cplusplus
+const MojoDeadline MOJO_DEADLINE_INDEFINITE = static_cast<MojoDeadline>(-1);
+#else
+#define MOJO_DEADLINE_INDEFINITE = ((MojoDeadline) -1);
+#endif
+
+// |MojoWriteMessageFlags|:
+#ifdef __cplusplus
+const MojoWriteMessageFlags MOJO_WRITE_MESSAGE_FLAG_NONE = 0;
+// TODO(vtl): Moar.
+#else
+#define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags) 0)
+// TODO(vtl): Moar.
+#endif
+
+// |MojoReadMessageFlags|:
+#ifdef __cplusplus
+const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_NONE = 0;
+const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0;

[darin (slow to review), 2013/09/25 06:06:07]

nit: add a comment explaining what MAY_DISCARD means.

[viettrungluu, 2013/09/26 17:59:15]

Done.

+// TODO(vtl): Moar.
+#else
+#define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags) 0)
+#define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags) 1 << 0)
+// TODO(vtl): Moar.
+#endif
+
+// Functions -------------------------------------------------------------------
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+MojoResult MojoClose(MojoHandle handle);
+
+MojoResult MojoWait(MojoHandle handle,
+                    MojoWaitFlags flags,
+                    MojoDeadline deadline);
+
+MojoResult MojoWaitMany(const MojoHandle* handles,
+                        const MojoWaitFlags* flags,
+                        uint32_t num_handles,
+                        MojoDeadline deadline);
+
+// TODO(vtl): flags? other params (e.g., queue sizes, max message sizes?)

[darin (slow to review), 2013/09/24 22:48:19]

Maybe we should have an attributes struct like pthreads.

  struct MessagePipeAttributes {
    int flags;
    ...
  };

Based on bits set in flags, we'd dereference fields on MessagePipeAttributes.

This way it is possible to add attributes to configure queue_sizes, etc. later.

+MojoResult MojoCreateMessagePipe(MojoHandle* handle_0, MojoHandle* handle_1);
+
+MojoResult MojoWriteMessage(MojoHandle handle,
+                            const void* bytes, uint32_t num_bytes,
+                            const MojoHandle* handles, uint32_t num_handles,
+                            MojoWriteMessageFlags flags);
+
+MojoResult MojoReadMessage(MojoHandle handle,

[darin (slow to review), 2013/09/25 06:06:07]

nit: it'd be good to include some documentation for these functions. what error
code gets returned when *num_bytes is too small?

btw, do we expect MojoReadMessage to always return exactly one complete message?
I think we probably should, but hmm...

[viettrungluu, 2013/09/25 18:22:16]

Yes, I still have to write documentation. :)
I expect MojoReadMessage to return only complete messages.

If the message is too large, it'll return the required size in
|*num_bytes|/|*num_handles|, unless it's in "may discard" mode in which case
it'll discard too-large messages. I pondered letting it do partial reads, but
decided that added more complexity than it's worth.

+                           void* bytes, uint32_t* num_bytes,
+                           MojoHandle* handles, uint32_t* num_handles,
+                           MojoReadMessageFlags flags);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+// C++ wrapper functions -------------------------------------------------------
+
 #ifdef __cplusplus
 namespace mojo {
 
 struct Handle { MojoHandle value; };
 
+inline MojoResult Close(Handle handle) {
+  return MojoClose(handle.value);
+}
+
+inline MojoResult Wait(Handle handle,
+                       MojoWaitFlags flags,
+                       MojoDeadline deadline) {
+  return MojoWait(handle.value, flags, deadline);
+}
+
+// TODO(vtl): C++ wrapper for |WaitMany()|.

[darin (slow to review), 2013/09/24 22:48:19]

We probably want to ensure that Handle is packed so that Handle* can be
reinterpret_cast'd to MojoHandle*.

[viettrungluu, 2013/09/26 17:59:15]

Done.

+
 }  // namespace mojo
 #endif
 
 #endif  // MOJO_PUBLIC_SYSTEM_CORE_H_