Dispatcher
in package
uses
BaseTraits
Defines a Dispatcher object which defines functions that are intended to run in the background. The Dispatcher objects allows us to dynamically create a private PHP script that can be called in the background, manages the process spawn queue, and enforces background process timeouts.
Table of Contents
Constants
- DISPATCH_SCRIPT = '/usr/local/pkg/RESTAPI/.resources/scripts/dispatch.sh'
- SCHEDULE_OPTIONS = ['hourly', 'daily', 'weekly']
Properties
- $async : bool
- $max_queue : int
- $schedule : string
- $timeout : int
- $full_name : string
- $package_includes : array<string|int, mixed>
- $pid_dir : string
- $pid_file : string
- $pid_file_prefix : string
- $required_packages : array<string|int, mixed>
- $schedule_command : string
- $short_name : string
Methods
- __construct() : mixed
- Constructs the Dispatcher object.
- get_class_fqn() : string
- Obtains the fully qualified name of the called class.
- get_class_shortname() : string
- Obtains the shortname of the called class.
- get_classes_in_namespace() : array<string|int, mixed>
- Obtains all classes associated with this class's current namespace.
- get_pid_file() : string
- Reads the PID file path that will be used for the next spawned process.
- get_running_processes() : array<string|int, mixed>
- Obtains the PIDs of any active processes spawned by this Dispatcher.
- kill_running_processes() : void
- Kills any running Dispatcher processes.
- log_error() : void
- Logs an error to the syslog.
- process() : void
- Runs the _process() directly. This method is essentially a wrapper for _process() that checks for required packages before starting. In almost every situation you should call spwan_process() instead of this method.
- setup_schedule() : CronJob|null
- Configures this Dispatcher to run on a schedule if the `schedule` property is set.
- spawn_process() : int
- Spawns a new process for this Dispatcher. If this Dispatcher has the $async property enabled, this will spawn the _process() method in the background. Otherwise, this behaves similar to the process() method by calling the _process() method synchronously, but this method enforces the $max_concurrency property unlike process().
- _process() : void
- Defines what should be done when the Dispatch process is spawned. In most cases, this will restart some service or perform computations that may take a long time. It is up to the child Dispatcher class to decide what is done here.
- check_required_packages() : void
- Checks if the required pfSense packages for this Dispatcher are installed and their required dependencies are imported.
Constants
DISPATCH_SCRIPT
public
mixed
DISPATCH_SCRIPT
= '/usr/local/pkg/RESTAPI/.resources/scripts/dispatch.sh'
Tags
SCHEDULE_OPTIONS
public
mixed
SCHEDULE_OPTIONS
= ['hourly', 'daily', 'weekly']
Tags
Properties
$async
public
bool
$async
= true
Indicates whether this Dispatcher object should spawn processes asynchronously (in the
background) or synchronously (waits for process to complete). If set to true, any spawn_process() method calls
will spawn the process in the background and immediately respond. If set to false, any spawn_process() will
wait until the process finishes to respond.
$max_queue
public
int
$max_queue
= 10
Sets the maximum number of processes this Dispatcher can have queued at one time. Attempts to spawn processes past this limit will result in a ServiceUnavailableError error.
$schedule
public
string
$schedule
= ''
Specifies the frequency in which this Dispatcher should be run on a schedule. Valid options are hourly,
daily, and weekly. Leave blank if this Dispatcher should not automatically run on a schedule.
$timeout
public
int
$timeout
= 300
Sets the maximum number of seconds that processes spawned by this Dispatcher can run for. After this time-frame, the process will be terminated. This ensures Dispatchers cannot spawn processes that run endlessly and crash the system.
$full_name
protected
string
$full_name
The full name of this Dispatcher. This value is automatically populated using the class FQN, but all slashes are removed. This value is used when reading and writing the Dispatcher's PID file.
$package_includes
protected
array<string|int, mixed>
$package_includes
= []
Assigns PHP files to include that are specific to one or more of the assigned $packages.
$pid_dir
protected
string
$pid_dir
Sets the directory where the Dispatcher PID file will be written. This file name must be unique for each Dispatcher process spawned.
$pid_file
protected
string
$pid_file
Sets the entire name of the PID file.
$pid_file_prefix
protected
string
$pid_file_prefix
The PID file name prefix. This value should contain this Dispatcher's $full_name.
$required_packages
protected
array<string|int, mixed>
$required_packages
= []
The pfSense packages required to run this Dispatcher. This must use the full pfSense package name including the pfSense-pkg- prefix.
$schedule_command
protected
string
$schedule_command
= ''
The shell command that will be used to call this Dispatcher on a schedule.
$short_name
protected
string
$short_name
The Dispatcher class's short name. This value is passed to the dispatch.sh helper script to indicate which Dispatcher class should be run.
Methods
__construct()
Constructs the Dispatcher object.
public
__construct([bool $async = true ]) : mixed
Parameters
- $async : bool = true
-
Set to
falseto prevent this Dispatcher from running the process in the background.
get_class_fqn()
Obtains the fully qualified name of the called class.
public
get_class_fqn() : string
Return values
string —The FQN for this object's class.
get_class_shortname()
Obtains the shortname of the called class.
public
get_class_shortname() : string
Return values
string —The shortname for this object's class.
get_classes_in_namespace()
Obtains all classes associated with this class's current namespace.
public
get_classes_in_namespace([bool $shortnames = false ]) : array<string|int, mixed>
Parameters
- $shortnames : bool = false
Return values
array<string|int, mixed> —An array of classes currently in this object's namespace
get_pid_file()
Reads the PID file path that will be used for the next spawned process.
public
get_pid_file() : string
Return values
stringget_running_processes()
Obtains the PIDs of any active processes spawned by this Dispatcher.
public
get_running_processes() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>kill_running_processes()
Kills any running Dispatcher processes.
public
kill_running_processes() : void
log_error()
Logs an error to the syslog.
public
static log_error(string $message) : void
Parameters
- $message : string
-
The error message to write to the syslog
process()
Runs the _process() directly. This method is essentially a wrapper for _process() that checks for required packages before starting. In almost every situation you should call spwan_process() instead of this method.
public
process(mixed ...$arguments) : void
Parameters
- $arguments : mixed
setup_schedule()
Configures this Dispatcher to run on a schedule if the `schedule` property is set.
public
setup_schedule() : CronJob|null
Return values
CronJob|null —Returns the CronJob created for this Dispatcher if a schedule is defined. Returns null
if no schedule was defined.
spawn_process()
Spawns a new process for this Dispatcher. If this Dispatcher has the $async property enabled, this will spawn the _process() method in the background. Otherwise, this behaves similar to the process() method by calling the _process() method synchronously, but this method enforces the $max_concurrency property unlike process().
public
spawn_process(mixed ...$arguments) : int
Parameters
- $arguments : mixed
-
Optional arguments to pass to the
_process()method.
Tags
Return values
int —The PID of the spawned process.
_process()
Defines what should be done when the Dispatch process is spawned. In most cases, this will restart some service or perform computations that may take a long time. It is up to the child Dispatcher class to decide what is done here.
protected
_process(mixed ...$arguments) : void
Parameters
- $arguments : mixed
check_required_packages()
Checks if the required pfSense packages for this Dispatcher are installed and their required dependencies are imported.
private
check_required_packages() : void