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.