Generated on for Gecode by doxygen 1.17.0

External control for the requested number of search workers. More...

#include <gecode/search.hh>

Classes

class  State

Public Member Functions

 WorkerControl (void) noexcept
 Construct an empty handle.
 WorkerControl (unsigned int requested)
 Construct an engaged handle with initial request requested (zero pauses).
 WorkerControl (const WorkerControl &control)
 Copy constructor.
WorkerControl & operator= (const WorkerControl &control)
 Assignment operator.
 ~WorkerControl (void)
 Destructor.
bool engaged (void) const noexcept
 Whether this handle is engaged.
unsigned int requested (void) const noexcept
 Return the requested number of workers (zero also denotes an empty handle).
void request (unsigned int workers)
 Request workers workers (zero pauses the engine).
unsigned int capacity (void) const noexcept
 Return the fixed worker capacity, or zero before attachment.

Detailed Description

External control for the requested number of search workers.

A worker control is a copyable handle. Copies share the same request and can be used concurrently. An empty handle disables adjustment. DFS and BAB support worker control, as do experimental AStar and CABS. The resolved Options::threads value fixes the engine's worker capacity. Requests range from zero to that capacity; zero pauses search without discarding its state. This also applies to an engine with capacity one. Without thread support, use controls from one thread; attaching a zero request or calling request(0) raises InvalidWorkerRequest.

For example, the caller can keep a handle for an external scheduler:

options.threads = 8;
options.worker_control = control;
DFS<Model> engine(root,options);
// Safe from another thread while engine.next() is running.
control.request(6);
control.request(0); // Pause
control.request(1); // Resume
Depth-first search engine.
Definition search.hh:1211
Search engine options
Definition search.hh:848
External control for the requested number of search workers.
Definition search.hh:773

Requests take effect cooperatively at scheduler boundaries. A decrease lets excess workers finish their current search action before parking. An increase wakes parked workers. Parked operating-system threads retain their stacks and search state, so capacity should cover the largest allocation the engine may receive. Adjustment preserves search correctness; parallel exploration order and search statistics remain nondeterministic.

A shared control identity can attach to one leaf engine only. Sharing it between engines, attaching it to an enclosing meta-engine, or reusing it after engine destruction raises WorkerControlInUse. Copies may outlive the engine; subsequent in-range requests are harmless. Engine destruction detaches its state but does not make the identity reusable.

Restart-based search retains its DFS or BAB leaf control across restarts. For portfolio search, give each asset a distinct control through its engine builder. Controlled assets require a parallel outer PBS; sequential PBS rejects them with WorkerControlInUse before consuming roots or builders. PBS completes each next() round after every active asset reports. A paused asset observes the internal round stop and reports without resuming search; if all active assets are paused, next() waits until one resumes.

The caller enforces any shared worker budget. Decrease one asset's request before increasing another's to keep the requested sum within that budget. Workers finishing their current actions can still cause temporary oversubscription. Gecode provides no acknowledgement that a decrease has taken effect and chooses no allocation policy.

Definition at line 773 of file search.hh.

Constructor & Destructor Documentation

◆ WorkerControl() [1/3]

Gecode::Search::WorkerControl::WorkerControl ( void )
noexcept

Construct an empty handle.

Definition at line 62 of file worker-control.cpp.

◆ WorkerControl() [2/3]

Gecode::Search::WorkerControl::WorkerControl ( unsigned int requested)
explicit

Construct an engaged handle with initial request requested (zero pauses).

Definition at line 65 of file worker-control.cpp.

◆ WorkerControl() [3/3]

Gecode::Search::WorkerControl::WorkerControl ( const WorkerControl & control)

Copy constructor.

Definition at line 68 of file worker-control.cpp.

◆ ~WorkerControl()

Gecode::Search::WorkerControl::~WorkerControl ( void )

Destructor.

Definition at line 84 of file worker-control.cpp.

Member Function Documentation

◆ operator=()

WorkerControl & Gecode::Search::WorkerControl::operator= ( const WorkerControl & control)

Assignment operator.

Definition at line 75 of file worker-control.cpp.

◆ engaged()

bool Gecode::Search::WorkerControl::engaged ( void ) const
noexcept

Whether this handle is engaged.

Definition at line 90 of file worker-control.cpp.

◆ requested()

unsigned int Gecode::Search::WorkerControl::requested ( void ) const
noexcept

Return the requested number of workers (zero also denotes an empty handle).

Definition at line 95 of file worker-control.cpp.

◆ request()

void Gecode::Search::WorkerControl::request ( unsigned int workers)

Request workers workers (zero pauses the engine).

Returns without waiting for workers to reach the requested count. Throws UninitializedWorkerControl for an empty handle, or InvalidWorkerRequest if workers exceeds the fixed capacity or is zero in a build without thread support.

Definition at line 101 of file worker-control.cpp.

◆ capacity()

unsigned int Gecode::Search::WorkerControl::capacity ( void ) const
noexcept

Return the fixed worker capacity, or zero before attachment.

Definition at line 129 of file worker-control.cpp.


The documentation for this class was generated from the following files: