Class \Prado\Util\TSignalsDispatcher

TSignalsDispatcher class.

This class handles linux process signals. It translates the signals into global events in PRADO. There are special handlers for SIGALRM to handle time based alarm callbacks and for SIGCHLD to handle specific Process ID.

The signals translate to global events as such: SIGALRM => fxSignalAlarm ~ SIGHUP => fxSignalHangUp ^ SIGINT => fxSignalInterrupt ^ SIGQUIT => fxSignalQuit ^ SIGTRAP => fxSignalTrap SIGABRT => fxSignalAbort ^ SIGUSR1 => fxSignalUser1 SIGUSR2 => fxSignalUser2 SIGTERM => fxSignalTerminate ^ SIGCHLD => fxSignalChild @ SIGCONT => fxSignalContinue SIGTSTP => fxSignalTerminalStop SIGTTIN => fxSignalBackgroundRead SIGTTOU => fxSignalBackgroundWrite SIGURG => fxSignalUrgent ^ Designates an exiting signal-event unless changed in the TSignalParameter. ~ SIGALRM has a special handler self::ring() to process and manage the time queue of callbacks and reset the alarm. @ SIGCHLD has a special handler self::delegateChild() to delegate to process specific handlers.

The signal handlers are stored and restored on self::attach()ing and self::detach()ing, respectively. This installs and uninstalls the class as the signals' handler through the self::__invoke() method.

Alarms may be added with (@see self::alarm()) and removed with self::disarm(). Alarms can be added without callbacks and will raise the fxSignalAlarm event without a time callback. By calling alarm() without parameters, the next alarm time is returned.

The methods self::hasEvent(), self::hasEventHandler, and self::getEventHandlers will accept process signals (int) as event names and translate it into the associated PRADO signal global event. These methods will also return the proper values for PID handlers, as well, by providing the event name in the format "pid:####" (where #### is the PID). hasEvent and getEventHandlers checks if the PID is running. To get the PID handler without validation use self::getPidHandlers().

Child PID handlers can be checked for with self::hasPidHandler(). The PID handlers can be retrieved with self::getPidHandlers() (besides using getEventHandlers with a special formatted event name [above]). Handlers can be attached to a specific PID with self::attachPidHandler() and detached with self::detachPidHandler(). Child PID handlers can be cleared with self::clearPidHandlers()

Class hierarchy

\Prado\Util\TSignalsDispatcher implements ISingleton uses TPriorityPropertyTrait

\Prado\TComponent

Author: Brad Anderson <belisoful@icloud.com>
Since: 4.3.0

Methods summary
`public`	`__construct() : mixed` Constructs the TSignalsDispatcher. The first instance is attached and set as the singleton.
`public`	`__invoke(int $signal[, null\|mixed $signalInfo = null ]) : mixed` This is called when receiving a system process signal. The global event for the signal is raised when the signal is received.
`public static`	`alarm([int $seconds = 0 ][, mixed $callback = null ]) : int\|null` Creates a new alarm callback at a specific time from now. If no callback is provided, then the alarm will raise `fxSignalAlarm` without a time-based callback. When calling alarm() without parameters, it will return the next alarm time.
`public`	`attach() : bool` This sets the signals' handlers to this object, attaches the original handlers to the PRADO global events at the {@see self::getPriorHandlerPriority()}. The alarm handler and Child handler is installed for routing.
`public`	`attachPidHandler(int $pid, mixed $handler[, null\|(numeric) $priority = null ][, bool $validate = false ]) : bool` Attaches a handler to a child PID at a priority. Optionally validates the process before attaching.
`public`	`clearPidHandlers(int $pid) : bool` Clears the Handlers for a specific PID.
`public`	`delegateChild(TSignalsDispatcher $sender, TSignalParameter $param) : mixed` The common SIGCHLD callback to delegate per PID. If there are specific PID handlers for a child, those PID callbacks are called. On an exit event, the PID handlers are cleared.
`public`	`detach() : bool` Detaches the singleton when it is the singleton. Prior signal handlers are restored.
`public`	`detachPidHandler(int $pid, mixed $handler[, mixed $priority = false ]) : mixed` Detaches a handler from a child PID at a priority.
`public static`	`disarm([int\|null $alarmTime = null ][, callable $callback = null ]) : int\|null` Disarms an alarm time-callback, at the optional time.
`public static`	`getAsyncSignals() : bool\|null` Gets whether the system is in async signals mode.
`public`	`getEventHandlers(mixed $name) : TWeakCallableCollection` Returns the list of attached event handlers for an 'on' or 'fx' event. This function also checks through all the behaviors for 'on' event lists when behaviors are enabled. The event name can be an integer Signal or a pid. Pid handlers have a prefix of 'pid:'.
`public`	`getPidHandlers(int $pid[, bool $validate = false ]) : TWeakCallableCollection\|null` Returns the Handlers for a specific PID.
`public static`	`getPriorHandler(int $signal[, bool $original = false ]) : mixed` This gets the signal handlers that were installed prior to the TSignalsDispatcher being attached.
`public static`	`getPriorHandlerPriority() : float\|null` This returns the priority of the signal handlers when they are installed as event handlers.
`public static`	`getSignalFromEvent(string $event) : int\|null` This translates the global event into the signal that raises the event.
`public`	`hasEvent(mixed $name) : bool` Determines whether an event is defined. The event name can be an integer Signal or a pid. Pid handlers have a prefix of 'pid:'. An event is defined if the class has a method whose name is the event name prefixed with 'on', 'fx', or 'dy'. Every object responds to every 'fx' and 'dy' event as they are in a universally accepted event space. 'on' event must be declared by the object. When enabled, this will loop through all active behaviors for 'on' events defined by the behavior. Note, event name is case-insensitive.
`public`	`hasEventHandler(string $name) : bool` Checks if an event has any handlers. This function also checks through all the behaviors for 'on' events when behaviors are enabled. The event name can be an integer Signal or a pid. Pid handlers have a prefix of 'pid:'. 'dy' dynamic events are not handled by this function.
`public`	`hasPidHandler(int $pid) : bool`
`public static`	`hasSignals() : bool`
`public static`	`nullAlarm(TSignalsDispatcher $sender, TSignalParameter $param) : mixed` The null alarm to simply trigger an alarm without callback
`public`	`raiseEvent(mixed $name, mixed $sender, mixed $param[, null\|mixed $responsetype = null ][, null\|mixed $postfunction = null ]) : mixed` Raises an event. This raises both inter-object 'on' events and global 'fx' events. Raises signal events by converting the $name as a Signal to the PRADO event for the signal.
`public`	`ring(TSignalsDispatcher $sender, TSignalParameter $signalParam) : mixed` The common SIGALRM callback time-processing handler raised by `fxSignalAlarm`. All alarm callbacks before or at `time()` are called. The next alarm time is found and the next signal alarm is set.
`public static`	`setAsyncSignals(bool $value) : bool\|null` Sets whether the system is in async signals mode. This is set to true on instancing. If this is set to false, then self::syncDispatch() must be called for signals to be processed. Any pending signals are dispatched when setting async to true.
`public static`	`setPriorHandlerPriority(float\|null $value) : bool` Sets the priority of the signal handlers when they are installed as event handlers.
`public static`	`singleton([bool $create = true ]) : object\|null` Returns the singleton of the class. The singleton is created if/when $create is true.
`public static`	`syncDispatch() : bool\|null` When PHP Signals are not in asynchronous mode, this must be called to dispatch the pending events. To change the async mode, use {@see self::setAsyncSignals()}.

Inherited methods
__call, __callStatic, __clone, __construct, __destruct, __get, __isset, __set, __sleep, __unset, __wakeup, addParsedObject, asa, attachBehavior, attachBehaviors, attachClassBehavior, attachEventHandler, callBehaviorsMethod, canGetProperty, canSetProperty, clearBehaviors, createdOnTemplate, detachBehavior, detachBehaviors, detachClassBehavior, detachEventHandler, disableBehavior, disableBehaviors, enableBehavior, enableBehaviors, evaluateExpression, evaluateStatements, fxAttachClassBehavior, fxDetachClassBehavior, getAutoGlobalListen, getBehaviors, getBehaviorsEnabled, getClassHierarchy, getEventHandlers, getListeningToGlobalEvents, getPriority, getSubProperty, hasEvent, hasEventHandler, hasMethod, hasProperty, isa, listen, raiseEvent, setPriority, setSubProperty, unlisten, _getZappableSleepProps, _priorityItemZappableSleepProps, getCallChain, getClassFxEvents, instanceBehavior, filter_prado_fx

Constants summary
`public mixed`	`EXIT_SIGNALS` The signals that exit by default.	`[SIGABRT => true, SIGBUS => true, SIGFPE => true, SIGHUP => true, SIGILL => true, SIGINT => true, SIGPIPE => true, SIGQUIT => true, SIGSEGV => true, SIGSYS => true, SIGTERM => true]`
`public mixed`	`FX_SIGNAL_ABORT`	`'fxSignalAbort'`
`public mixed`	`FX_SIGNAL_ALARM`	`'fxSignalAlarm'`
`public mixed`	`FX_SIGNAL_BACKGROUND_READ`	`'fxSignalBackgroundRead'`
`public mixed`	`FX_SIGNAL_BACKGROUND_WRITE`	`'fxSignalBackgroundWrite'`
`public mixed`	`FX_SIGNAL_CHILD`	`'fxSignalChild'`
`public mixed`	`FX_SIGNAL_CONTINUE`	`'fxSignalContinue'`
`public mixed`	`FX_SIGNAL_HANG_UP`	`'fxSignalHangUp'`
`public mixed`	`FX_SIGNAL_INTERRUPT`	`'fxSignalInterrupt'`
`public mixed`	`FX_SIGNAL_QUIT`	`'fxSignalQuit'`
`public mixed`	`FX_SIGNAL_TERMINAL_STOP`	`'fxSignalTerminalStop'`
`public mixed`	`FX_SIGNAL_TERMINATE`	`'fxSignalTerminate'`
`public mixed`	`FX_SIGNAL_TRAP`	`'fxSignalTrap'`
`public mixed`	`FX_SIGNAL_URGENT`	`'fxSignalUrgent'`
`public mixed`	`FX_SIGNAL_USER1`	`'fxSignalUser1'`
`public mixed`	`FX_SIGNAL_USER2`	`'fxSignalUser2'`
`public callable`	`NULL_ALARM`	`[self::class, 'nullAlarm']`
`public mixed`	`SIGNAL_MAP`	[ SIGALRM => self::FX_SIGNAL_ALARM, // Alarm signal. Sent by pcntl_alarm when the time is over. SIGHUP => self::FX_SIGNAL_HANG_UP, // Hangup signal. Sent to a process when its controlling terminal is closed. SIGINT => self::FX_SIGNAL_INTERRUPT, // Interrupt signal. Typically generated by pressing Ctrl+C. SIGQUIT => self::FX_SIGNAL_QUIT, // Quit signal. Similar to SIGINT but produces a core dump when received by the process. SIGTRAP => self::FX_SIGNAL_TRAP, // Trace/breakpoint trap signal. Used by debuggers to catch trace and breakpoint conditions. SIGABRT => self::FX_SIGNAL_ABORT, // Abort signal. Sent by the process itself to terminate due to a critical error condition. SIGUSR1 => self::FX_SIGNAL_USER1, // User-defined signal 1. SIGUSR2 => self::FX_SIGNAL_USER2, // User-defined signal 2. SIGTERM => self::FX_SIGNAL_TERMINATE, // Termination signal. Typically used to request graceful termination of a process. SIGCHLD => self::FX_SIGNAL_CHILD, // Child signal. Sent to a parent process when a child process terminates. SIGCONT => self::FX_SIGNAL_CONTINUE, // Continue signal. Sent to resume a process that has been stopped. SIGTSTP => self::FX_SIGNAL_TERMINAL_STOP, // Terminal stop signal. Sent by pressing Ctrl+Z to suspend the process. SIGTTIN => self::FX_SIGNAL_BACKGROUND_READ, // Background read signal. Sent to a process when it attempts to read from the terminal while in the background. SIGTTOU => self::FX_SIGNAL_BACKGROUND_WRITE, // Background write signal. Sent to a process when it attempts to write to the terminal while in the background. SIGURG => self::FX_SIGNAL_URGENT, ]

Inherited constants
`\Prado\TComponent::GLOBAL_RAISE_EVENT_LISTENER`

Classes

Interfaces

Traits

Search results

Class \Prado\Util\TSignalsDispatcher

Class hierarchy