Function

Summary

Waits until there is an object in the mailbox

Package

mp

Signature

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

Arguments

mailbox

A mailbox.

wait-reason

A string or nil.

timeout

A non-negative number 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 number, 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 the 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 the result of mailbox-wait is reliable only if you know that the current process is the only process that may read from the mailbox.

The wait-reason argument 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.

See also

mailbox-not-empty-p
mailbox-empty-p
mailbox-peek
mailbox-send
mailbox-wait-for-event
mailbox-read