Function

Summary

Creates and runs a wait-state-collection.

Package

comm

Signature

create-and-run-wait-state-collection name &key handler with-backtrace => wait-state-collection

Arguments

name

A Lisp object that names the collection. It is used only for printing.

handler

nil, t, the keyword :abort or a function.

with-backtrace

The keyword:bug-form, t, the keyword :quick, or nil.

Values

wait-state-collection

A wait-state-collection.

Description

The function create-and-run-wait-state-collection creates and runs a wait-state-collection.

create-and-run-wait-state-collection creates a wait-state-collection and then starts a new process which calls loop-processing-wait-state-collection on the new wait-state-collection (and therefore activates it), and returns it as wait-state-collection. The new process has process name "Loop Collection name". When loop-processing-wait-state-collection exits, wait-state-collection is closed and the other process exits too.

You can use wait-state-collection-stop-loop to make loop-processing-wait-state-collection exit, and hence close wait-state-collection and make the process go away. Calling process-terminate on the process itself can also be used, because it will use wait-state-collection-stop-loop.

handler specifies handling of errors that occur on the process in which the collection is run. The values have the following effects:

nil

No handling.

:abort

Abort (calls the function cl:abort).

t

Print the condition to the standard output, and unless with-backtrace is nil produces a backtrace, and then aborts.

A function

Must be a function of three arguments when with-backtrace is non-nil, or two arguments when with-backtrace is nil. When a serious condition is signaled, the handler is called inside the context of the error (like a handler in cl:handler-bind).

When with-backtrace is non-nil:

handler object condition backtrace-string

When with-backtrace is nil:

handler object condition

The object argument is the object that is responsible for the error. Currently this is always the async-io-state with which the callback that caused the error is associated. If there is an error outside a callback (which should not happen, unless there is a bug), then object is nil. condition is the condition that is signaled. backtrace-string is a string which is the result of producing a backtrace. If the handler returns, (cl:abort) is called.

with-backtrace controls whether a backtrace is produced when handler is t or a function. It is passed to output-backtrace as the first argument. See output-backtrace for details.

The default value of handler is nil. The default value of with-backtrace is :bug-form.

wait-state-collection can be used immediately by passing it to one of the create-async-io-state* functions.

Notes

1. The wait-state-collection wait-state-collection does nothing by itself. You need to create and use async-io-state objects to actually do something.
2. Aborting by the handler is done by calling (cl:abort), which aborts to the closest enclosing abort restart. If your code establishes such a restart around the error, the aborting will abort to it. Otherwise it will abort back to the loop of waiting and calling.
3. Real applications will probably always pass the handler.
4. While the handler is run, no further processing is done in the collection. Therefore the handler should not do a significant amount of work.

See also

wait-state-collection-stop-loop
create-async-io-state-and-connected-tcp-socket
create-async-io-state-and-connected-udp-socket
create-async-io-state
create-async-io-state-and-udp-socket
accept-tcp-connections-creating-async-io-states