Add moar documentation. (Mostly about handles, some about synchronous use of message pipes.) R=vardhan@google.com Review URL: https://codereview.chromium.org/1756603003 .
diff --git a/docs/intro/handles.md b/docs/intro/handles.md index c59105c..b0b9459 100644 --- a/docs/intro/handles.md +++ b/docs/intro/handles.md
@@ -1,3 +1,29 @@ # Mojo handles (objects) -**TODO(vtl)** +Mojo handles are analogous to Unix file descriptors or Windows `HANDLE`s. That +is, they are basically-opaque integers that a program can use to refer to system +resources. Like their Unix and Windows equivalents, a Mojo handle value only has +meaning within a given process. + +That said, there are some differences: +* There is a single value, 0, that is guaranteed to never be a valid Mojo + handle. This is unlike Unix, where all negative file descriptors are usually + taken to be invalid, even if -1 is often taken to be the "canonical" invalid + file descriptor value. +* The allocation of Mojo handle values is not specified. This is unlike Unix, + where file descriptors are allocated sequentially, with the lowest (positive) + unused value allocated. +* Unlike Windows, there are no "pseudohandles". That is, there is no Mojo handle + value whose meaning is context dependent (within the same process). +* In general, Mojo handles need not be duplicatable, whereas their Unix and + Windows equivalents can universally be duplicated. +* Mojo handles can be sent across [message pipes](message_pipes.md). Unlike + sending file descriptors over Unix domain sockets (using `SCM_RIGHTS`), this + is done with transfer semantics: after a message with attached Mojo handles is + sent, the Mojo handle values become invalid in the sending process. (Even if + the receiving process is the same as the sending process, the received Mojo + handle values will probably be different from the values that were sent.) +* Mojo handles have a well-defined life-cycle, and are only invalidated by + either transfer across a message pipe (as above) or by closing them. Unlike + Unix's overloaded `close()` (which may fail due to data loss, i.e., inability + to flush), closing a (valid) Mojo handle never fails.
diff --git a/docs/intro/message_pipes.md b/docs/intro/message_pipes.md index cf9959e..abe3013 100644 --- a/docs/intro/message_pipes.md +++ b/docs/intro/message_pipes.md
@@ -11,13 +11,13 @@ properties). That said, Mojo provides a *standard* way of communicating over message pipes, -namely via a standardized protocol together with [Mojom IDL](mojom.md) files. +namely via a standardized protocol together with [Mojom](mojom.md) IDL files. ## Messages A *message* consists of two things: * a finite sequence of bytes, and -* a finite sequence of Mojo handles. +* a finite sequence of [Mojo handles](handles.md). Both of these are determined when the message is sent (or *written*). Messages are *framed* in the sense that they are "atomic" units: they are sent and @@ -75,4 +75,44 @@ ## "Synchronous" operation -**TODO(vtl)** +Though message pipes are asynchronous as discussed above, they may be used in a +synchronous fashion: immediately after sending a *request* message, one can then +just block and wait for the *response* message (and then read it and process +it). Of course, this requires that the protocol support this: +* Message pipes must be used in a "directional" way: there must be fixed request + and response directions or, equivalently, one endpoint belongs to the *client* + and the other to the *server* (or *impl*). (Historical note: This is the case + for the current Mojom protocol, but not in previous versions.) The issue here + is that without this, the sender of the request messages may have to process + incoming request messages from its peer. +* Request messages must have unique response messages. (In the Mojom protocol, + request messages have optional unique responses. For messages without + responses, one can just proceed immediately without waiting. However, without + response messages there may be flow control issues; again, see above.) The + important point is that for each request message, there is a well-defined + number of response messages for each request and not arbitrary "callback" + messages. +* The sending of a response message must not depend on a future action of the + client. (This is a higher-level semantic that is not enforced by the Mojom + protocol. E.g., one may define a Mojom interface in which the response to a + message *Foo* isn't sent until the client sends a request *Bar*.) + +That said, whether one wants to, or even can, use this synchronous mode of +operation may depend on a number of things: +* For message-loop-centric programming languages, this mode is at best + undesirable (and possibly infeasible, depending on what facilities are exposed + to user code). (E.g., this is the case for JavaScript and Dart.) +* Similarly, on a message-loop programming model (in which threads -- if there + are more than one -- are mostly coordinated by "message passing"), it is + typically undesirable to block any thread (with a message loop). Indeed, if + other message pipes are serviced by a message loop, blocking the thread may + result in deadlock. (E.g., this is the usual programming model for the + standard Mojom C++ bindings.) +* Even when blocking is permissible, it may not be desirable to do so: + advancement of the program then relies on trusting the server to be + responsive and send responses in a timely fashion. +* Mixing asynchronous and synchronous operation is problematic: one cannot send + a request and synchronously wait for a response while responses to other + messages are still pending. (Theoretically, one could buffer such other + responses until the response to particular request is received, and process + those other responses later, but this would be dubious at best.)