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.