All Manuals > CAPI User Guide and Reference Manual > 21 CAPI Reference Entries

apply-in-pane-process-if-alive

apply-in-pane-process-wait-single

apply-in-pane-process-wait-multiple Functions

Summary

Applies a function in the process associated with a pane, and optionally waits for and returns its values.

Package

capi

Signatures

apply-in-pane-process-if-alive pane function &rest args => alivep

apply-in-pane-process-wait-single pane timeout function &rest args => result, status

apply-in-pane-process-wait-multiple pane timeout function &rest args => results, status

Arguments
pane
A CAPI element or pinboard object.
function
A function or an fbound symbol.
args
Any Lisp objects.
timeout
A non-negative real (number of seconds) or nil.
Values
alivep
A boolean.
result
Any Lisp object.
status
nil, t or :timeout.
results
A list of Lisp objects.
Description

The function apply-in-pane-process-if-alive applies function to args in the process that is associated with pane , if pane is "alive". This is like apply-in-pane-process except that function is called only if pane is alive. The meaning of "alive" and the value of alivep are as defined for execute-with-interface-if-alive.

If pane does not have a process, then function is not called.

The return value of apply-in-pane-process-if-alive, alivep, is true if the pane is "alive" and false otherwise.

apply-in-pane-process-wait-single applies function to args like apply-in-pane-process-if-alive, and then waits for function to return. If the call returns successfully, result is the first return value of the call to function, and status is t. If pane is not "alive", result and status are nil. If timeout is non-nil and the call did not return within timeout seconds, then result is nil and status is :timeout.

apply-in-pane-process-wait-multiple is the same as apply-in-pane-process-wait-single except for the returned values. If the call to function returns successfully, results is a list of the values that function returned and status is t. If pane is not "alive", result and status are nil. If timeout is non-nil and the call did not return within timeout seconds, then result is nil and status is :timeout.

Notes

Even if apply-in-pane-process-if-alive returns true for alivep, function is not guaranteed to be called. For example, the process of pane might be killed or hang.

After timeout has expired in apply-in-pane-process-wait-multiple or apply-in-pane-process-wait-single, function may or may not have been called.

apply-in-pane-process-wait-multiple and apply-in-pane-process-wait-single work by creating a mp:mailbox, applying (in the same way that apply-in-pane-process-if-alive does) a lambda that puts the result(s) of function in the mailbox, and then wait for the mailbox. It is quite easy to write your own version of this if you need additional features (for example, error handling).

See also

apply-in-pane-process
execute-with-interface-if-alive
4.1 The correct thread for CAPI operations
7 Programming with CAPI Windows


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:27