pfSense-pkg-RESTAPI

Cache extends Dispatcher
in package
uses BaseTraits

Defines a Cache object. Cache objects are a type of Dispatcher object that is intended to fetch data from an external source and store the output to a local cache file that periodically gets updated. This is helpful when handling data that may take a long time to populate, or data that may have upstream rate limits that need to be respected.

Table of Contents

Constants

CACHE_DIR  = '/usr/local/pkg/RESTAPI/.resources/cache/'
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
Overrides the Dispatcher's default __construct method to add custom behavior for Cache construction.
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_file_path()  : string
Obtains the filepath of this object's cache file.
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
Refreshes the cache by fetching new data using the `get_data_to-cache()` method and saving it as a JSON file to the cache directory.
read()  : array<string|int, mixed>
Obtains the cached data from the cache file.
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.
get_data_to_cache()  : array<string|int, mixed>
Fetches the data that should be stored in the cache file.
check_required_packages()  : void
Checks if the required pfSense packages for this Dispatcher are installed and their required dependencies are imported.

Constants

CACHE_DIR

public mixed CACHE_DIR = '/usr/local/pkg/RESTAPI/.resources/cache/'
Tags
const

CACHE_DIR The absolute file path to the directory where cache files are stored.

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()

Overrides the Dispatcher's default __construct method to add custom behavior for Cache construction.

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_file_path()

Obtains the filepath of this object's cache file.

public final get_file_path() : string
Tags
returns

string The absolute filepath of the cache file for this object.

Return values
string

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()

Refreshes the cache by fetching new data using the `get_data_to-cache()` method and saving it as a JSON file to the cache directory.

public final process(mixed ...$arguments) : void
Parameters
$arguments : mixed

read()

Obtains the cached data from the cache file.

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

array The cached data in an array representation.

Return values
array<string|int, 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()

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

get_data_to_cache()

Fetches the data that should be stored in the cache file.

protected get_data_to_cache() : array<string|int, mixed>
Tags
returns

array The data to store in the cache.

throws
ServerError

When this method is called but the get_data_to_cache() method has not been overwritten by the child class.

Return values
array<string|int, 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