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.
