Generic Function | Package: mp | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 This page is new in 10.1.

## discard-process-pool-work-item

Arguments: work-item &key kill wait reason

This generic function allows users to stop a work-item launched with process-pool-run. As with other operators that cancel or stop running work items (cancel-process-pool-work and cancel-process-pool-worker), there is flexibility about whether to actually kill the running work item function or to let it complete and then do some clean up.

The work-item argument must be a `process-pool-work-item`. The kill keyword argument can be `t`, `nil`, or a function name or object. The function must run with no arguments. reason is a symbol or string which will be added to the work-item's `error` slot. It defaults to `:discard-work-item`. The wait argument can be `t` (or a non-`nil` value that is not a number), `nil`, or a number.

Here are the various cases:

### The work-item is neither running nor on a process-pool queue

The work-item may have completed running or may never have been added to a `process-pool` queue, either because the queue was full when process-pool-run was called or because the work-item was created with make-process-pool-work-item and never assigned to a process-pool. In either case, discard-process-pool-work-item takes no action other than returning `:idle`.

### The work-item is in a process-pool queue but is not running

The work-item is removed from the queue and discard-process-pool-work-item returns `:dequeued`.

### The work-item is running

'Running' means one of the three functions associated with the work-item (the `report-start` function, the work-item `function`, and the `report-end` function) is executing or about to execute. What happens depends on the value of the kill. The value of the wait argument is ignored when kill is either `t` or `nil`.

kill can be `t`, `nil`, or a function designator naming a function that will run with no arguments. Here are the effects of those values:

- kill is `t`: the effect is equivalent to calling cancel-process-pool-work in the work-item function or one of the report functions, whichever happens to be running at the time of the interrupt. Also, the work-item's `error` slot is set to the value of the reason keyword argument (default `:discard-work-item`), and the single value `:killed` is returned.
- kill is `nil`: the work-item is left running. discard-process-pool-work-item returns two values: `nil` and `:running`.
- kill is a function designator: this function is used as the interrupt function to mp:process-interrupt, that is, this form is evaluated:

      (mp:process-interrupt the-process-running-work-item the-value-of-kill)

  What happens next depends on the value of the wait argument. If wait is `nil`, discard-process-pool-work-item returns two values: `nil` and `:interrupted`. If wait is non-`nil` but not a number, wait until the work-item function exits and discard-process-pool-work-item returns `:killed`. If wait is a number, wait up that number of seconds. If the work-item function completes, discard-process-pool-work-item returns `:killed`; if the work-item function does not complete, discard-process-pool-work-item returns `nil` and `:running`.

See Process pools in multiprocessing.htm for more information on process pools.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page is new in the 10.1 release.
Created 2019.8.20.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 This page is new in 10.1.