pfSense-pkg-RESTAPI

DNSResolverApplyDispatcher extends Dispatcher
in package

Defines a Dispatcher for applying changes to the DNS Resolver configuration.

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
Reloads the DNS Resolver and associated services.
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
const

DISPATCH_SCRIPT The absolute file path to the dispatch.sh helper script.

SCHEDULE_OPTIONS

public mixed SCHEDULE_OPTIONS = ['hourly', 'daily', 'weekly']
Tags
const

SCHEDULE_OPTIONS The cron event schedules supported by Dispatchers.

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 false to 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
string

get_running_processes()

Obtains the PIDs of any active processes spawned by this Dispatcher.

public get_running_processes() : array<string|int, mixed>
Tags
returns

array An array of PIDs of processes spawned by this Dispatcher.

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
throws
ServiceUnavailableError

When the maximum number of processes allowed by $max_concurrency is exceeded.

Return values
int —

The PID of the spawned process.

_process()

Reloads the DNS Resolver and associated services.

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
Tags
throws
FailedDependencyError

When the Dispatcher requires a pfSense package that is not installed.

throws
FailedDependencyError

When a package requires a PHP include file that could not be found.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results