create-and-run-wait-state-collection

create-and-run-wait-state-collection 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

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.
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.
Real applications will probably always pass the handler.
While the handler is run, no further processing is done in the collection. Therefore the handler should not do a significant amount of work.