mailbox-wait

mailbox-wait Function

Summary

Waits until there is an object in the mailbox.

Package

Signature

mailbox-wait mailbox &optional wait-reason timeout => result

Arguments

`mailbox`⇩	A mailbox.
`wait-reason`⇩	A string or `nil`.
`timeout`⇩	A non-negative real or `nil`.

Values

result⇩

A boolean.

Description

The function mailbox-wait waits until there is an object in the mailbox mailbox.

If mailbox is empty and timeout is nil, then mailbox-wait blocks until an object is placed in mailbox. If mailbox is empty and timeout is a non-negative real, then mailbox-wait blocks until an object is placed in mailbox or timeout seconds have passed. If there is no object after timeout seconds, then mailbox-wait returns nil. Once there is an object in mailbox, mailbox-wait returns t.

Note that mailbox-wait does not remove the object from mailbox, in contrast to mailbox-read which does.

Note that if there are multiple processes reading from mailbox, another process may read the object from it, so result is reliable only if you know that the current process is the only process that may read from the mailbox.

wait-reason defaults to a string:

"Waiting for message in #<Mailbox...>"

and will be the value returned by process-whostate while mailbox-wait is blocking.

The default value of timeout is nil.

mailbox-wait arranges for immediate notification when an object is placed in mailbox (unless other processes ware waiting too, in which case one of the processes is notified immediately). It is therefore better than using process-wait with mailbox-not-empty-p because it does not rely on the scheduler to wake it up. It is also less expensive because does not add work to the scheduler.