docs/intro/handles.md

# Mojo handles (objects)

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.