[docs] Clarify level-triggered nature of signals
Previously, the docs were unclear if you read them with a pre-conceived
notion that signals were edge-triggered (as "signals" are in POSIX).
Change-Id: I52bbd7eb652002ecd5479926a6fa1c6c677a4985
diff --git a/docs/syscalls/object_signal.md b/docs/syscalls/object_signal.md
index e242eba..6e35194 100644
--- a/docs/syscalls/object_signal.md
+++ b/docs/syscalls/object_signal.md
@@ -6,7 +6,6 @@
object_signal_peer - signal an object's peer
-
## SYNOPSIS
```
@@ -19,28 +18,28 @@
## DESCRIPTION
-**zx_object_signal**() and **zx_object_signal_peer**() set and clear the userspace-accessible
-signal bits on an object or on the object's peer, respectively. A object peer is the opposite
-endpoint of a *channel*, *socket*, *fifo*, or *eventpair*.
+**zx_object_signal**() and **zx_object_signal_peer**() assert and deassert the
+userspace-accessible signal bits on an object or on the object's peer,
+respectively. A object peer is the opposite endpoint of a *channel*, *socket*,
+*fifo*, or *eventpair*.
-Most of the 32 signals are reserved for system use and are assigned to per-object functions, like
-*ZX_CHANNEL_READABLE* or *ZX_TASK_TERMINATED*. 8 signals are available for userspace processes
-to use as they see fit: *ZX_USER_SIGNAL_0* through *ZX_USER_SIGNAL_7*.
+Most of the 32 signals are reserved for system use and are assigned to
+per-object functions, like *ZX_CHANNEL_READABLE* or *ZX_TASK_TERMINATED*. There
+are 8 signal bits available for userspace processes to use as they see fit:
+*ZX_USER_SIGNAL_0* through *ZX_USER_SIGNAL_7*.
*Event* objects also allow control over the *ZX_EVENT_SIGNALED* bit.
*Eventpair* objects also allow control over the *ZX_EVENTPAIR_SIGNALED* bit.
-The *clear_mask* is first used to clear any bits indicated, and then the *set_mask*
-is used to set any bits indicated.
-
+The *clear_mask* is first used to clear any bits indicated, and then the
+*set_mask* is used to set any bits indicated.
## RETURN VALUE
**zx_object_signal**() and **zx_object_signal_peer**() return **ZX_OK** on success.
In the event of failure, a negative error value is returned.
-
## ERRORS
**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.
@@ -58,7 +57,6 @@
*ZX_RIGHT_WRITE* is used to gate access to signal bits. This will likely change.
-
## SEE ALSO
[event_create](event_create.md),
diff --git a/docs/syscalls/object_wait_async.md b/docs/syscalls/object_wait_async.md
index c4bc782..dc7cfb4 100644
--- a/docs/syscalls/object_wait_async.md
+++ b/docs/syscalls/object_wait_async.md
@@ -27,7 +27,7 @@
The *options* argument can be either **ZX_WAIT_ASYNC_ONCE** or **ZX_WAIT_ASYNC_REPEATING**.
In both cases, *signals* indicates which signals on the object specified by *handle*
-will cause a packet to be enqueued, and if **any** of those signals are active when
+will cause a packet to be enqueued, and if **any** of those signals are asserted when
**object_wait_async**() is called, or become asserted afterwards, a packet will be
enqueued on *port*.
@@ -35,10 +35,9 @@
waiting ends. No further packets will be enqueued.
In the case of **ZX_WAIT_ASYNC_REPEATING** the asynchronous waiting continues until
-canceled. If any of *signals* are asserted and a packet is not currently in *port*'s
-queue on behalf of this wait, a packet is enqueued. If a packet is already in the
-queue, the packet's *observed* field is updated. This mode acts in an edge-triggered
-fashion.
+canceled. If any of *signals* are asserted and a packet is not currently in *port*'s
+queue on behalf of this wait, a packet is enqueued. If a packet is already in the
+queue, the packet's *observed* field is updated.
In either mode, **port_cancel**() will terminate the operation and if a packet was
in the queue on behalf of the operation, that packet will be removed from the queue.
@@ -72,7 +71,6 @@
See [signals](../signals.md) for more information about signals and their terminology.
-
## SEE ALSO
[port_cancel](port_cancel.md).
diff --git a/docs/syscalls/object_wait_many.md b/docs/syscalls/object_wait_many.md
index cdd707a..b41f815 100644
--- a/docs/syscalls/object_wait_many.md
+++ b/docs/syscalls/object_wait_many.md
@@ -21,14 +21,17 @@
## DESCRIPTION
**object_wait_many**() is a blocking syscall which causes the caller to
-wait until at least one of the specified signals is pending on one of
-the specified *items*, or until *deadline* passes, whichever comes first.
+wait until either the *deadline* passes or at least one of the specified
+signals is asserted by the object to which the associated handle refers.
+If an object is already asserting at least one of the specified signals,
+the wait ends immediately.
The caller must provide *count* zx_wait_item_ts in the *items* array,
containing the handle and signals bitmask to wait for for each item.
The *deadline* parameter specifies a deadline with respect to
-**ZX_CLOCK_MONOTONIC**. **ZX_TIME_INFINITE** is a special value meaning wait forever.
+**ZX_CLOCK_MONOTONIC**. **ZX_TIME_INFINITE** is a special value meaning wait
+forever.
Upon return, the *pending* field of *items* is filled with bitmaps indicating
which signals are pending for each item.
diff --git a/docs/syscalls/object_wait_one.md b/docs/syscalls/object_wait_one.md
index 58d7374..b8defbc 100644
--- a/docs/syscalls/object_wait_one.md
+++ b/docs/syscalls/object_wait_one.md
@@ -18,8 +18,9 @@
## DESCRIPTION
**object_wait_one**() is a blocking syscall which causes the caller to
-wait until at least one of the specified *signals* has been observed on
-the object *handle* refers to or *deadline* passes.
+wait until either the *deadline* passes or the object to which *handle* refers
+asserts at least one of the specified *signals*. If the object is already
+asserting at least one of the specified *signals*, the wait ends immediately.
Upon return, if non-NULL, *observed* is a bitmap of *all* of the
signals which were observed asserted on that object while waiting.
@@ -30,7 +31,8 @@
once the last message in its queue is read).
The *deadline* parameter specifies a deadline with respect to
-**ZX_CLOCK_MONOTONIC**. **ZX_TIME_INFINITE** is a special value meaning wait forever.
+**ZX_CLOCK_MONOTONIC**. **ZX_TIME_INFINITE** is a special value meaning wait
+forever.
## RETURN VALUE
