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

## process-pool-run

Arguments: pool &key work function arguments name report-start report-end data (queue-p t)

The default method of this generic function (specializing on `nil` and `process-pool` objects) does two things:

1. Creates a new `process-pool-work-item` if the work argument is `nil`, or modfies the `process-pool-work-item` specified by the work argument.
2. Processes that work-item if possible. Processing means running it in the pool specified by the pool argument if that pool has an available idle process or can create a new process, or queueing it in that pool if no idle process is available. If there is no idle process and the queue is full (see process-pool-work-limit which specifies the maximum queue size), then nothing is further is done to the work-item.

Two values are returned:

1. The result of attempting to run or queue the work item. This returned value is one of: `:created` (meaning the work-item started to run in a newly-created pool process); `:started` (meaning the work-item started to run in an existing idle pool process); `:queued` (meaning the work-item was added to the queue of unrun work-items for the pool); or `nil` (meaning the work-item was neither run nor queued).
2. The newly-created or modified process-pool-work-item. While this operator does typically modify work-items passed in as the value of the work argument, it can return the work-item unmodified if the keyword arguments passed in do not necessitate modification. If the first value is `nil`, meaning the work-item was neither run nor queued, the work-item can be later passed as the work keyword argument to process-pool-run in order to attempt to run or queue it again.

Here are the arguments and their meanings:

- pool: This required argument must be a `process-pool` instance or `nil`. If it is a `process-pool` instance, the system will try to start running a `process-pool-work-item` in one of the pool's processes. If it is `nil`, the system will try to start running a `process-pool-work-item` in the default process-pool (see ensure-default-process-pool). It is an error to specify `nil` when there is no default process-pool. The work-item to be run is either created using the keyword arguments to process-pool-run or is an existing work-item specified by the work keyword argument, possibly modified by the other keyword arguments.
- work: The value of this keyword argument should be either `nil` or an existing `process-pool-work-item`. If the value is `nil` (which is the default), a new `process-pool-work-item` will be created with slots specified by the additional keyword arguments to process-pool-run. If the value is an existing work-item (created either by make-process-pool-work-item or by a previous call to process-pool-run), that work-item will be modified by supplied process-pool-run keyword arguments. Note that unsupplied keyword arguments to process-pool-run do not modify the corresponding slot values of an existing work-item.
- function: The actual work of a process-pool-work-item is performed by applying the work-item function, the value of this argument, to the work-item arguments, described below. If supplied, the `function` slot of the supplied (by the work argument) or newly-created `process-pool-work-item` will be set to the value of this argument. If unsupplied, the `function` slot will be `nil` in a newly-created `process-pool-work-item` and unchanged in one supplied as the value of the work argument. When the function is `nil`, the work-item does nothing except run the report-start and report-end functions.
- arguments: The actual work of a process-pool-work-item is performed by applying the work-item function (described above) to the work-item arguments, the value of this argument. If supplied, the `arguments` slot of the supplied (by the work argument) or newly-created `process-pool-work-item` will be set to the value of this argument. If unsupplied, the `data` slot will be `nil` in a newly-created `process-pool-work-item` and unchanged in one supplied as the value of the work argument.
- name: The value of this keyword argument provides the name that will be used as the process name when the work item is run in a process. If supplied, the `name` slot of the supplied (by the work argument) or newly-created `process-pool-work-item` will be set to the value of this argument. If unsupplied, the `name` slot will be created by the system in a newly-created `process-pool-work-item` and unchanged in one supplied as the value of the work argument.
- report-start: If supplied, the `report-start` slot of the supplied (by the work argument) or newly-created `process-pool-work-item` will be set to the value of this argument. If unsupplied, the `report-start` slot will be `nil` in a newly-created `process-pool-work-item` and unchanged in one supplied as the value of the work argument. A value of `nil` for the `report-start` slot means the `process-pool` report-start function will be run at the beginning of running the work-item. It does not mean that no report-start function will be run.
- report-end: If supplied, the `report-end` slot of the supplied (by the work argument) or newly-created `process-pool-work-item` will be set to the value of this argument. If unsupplied, the `report-end` slot will be `nil` in a newly-created `process-pool-work-item` and unchanged in one supplied as the value of the work argument. A value of `nil` for the `report-end` slot means the `process-pool` report-end function will be run at the end of running the work-item. It does not mean that no report-end function will be run.
- data: If supplied, the `data` slot of the supplied (by the work argument) or newly-created `process-pool-work-item` will be set to the value of this argument. If unsupplied, the `data` slot will be `nil` in a newly-created `process-pool-work-item` and unchanged in one supplied as the value of the work argument.
- queue-p: If the value of this keyword argument is non-`nil` (the default), then if the work-item cannot be run immediately because the maximum number of active processes in the pool are already running (see process-pool-active-limit), then the work-item will be added to the pool queue if possible (see process-pool-work-limit). If queue-p is `nil`, the work-item will not be queued if it cannot immediately be run and process-pool-run will return `nil` as its first return value.

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.