/** * Returns an installed signal database or null if it cannot be found. * * @param object $signal SIG * * @return null|object \XPSPL\database\Signals */ function xp_get_signal($signal) { if (!$signal instanceof \XPSPL\SIG) { $signal = new \XPSPL\SIG(); } return XPSPL::instance()->find_signal_database($signal); }
/** * Execute a function after a signal has been emitted. * * @param object $signal \\XPSPL\\SIG * @param callable|process $process PHP Callable or \\XPSPL\\Process. * * @return object \\XPSPL\\Process * * @example * * Example #1 Basic Usage * * .. code-block:: php * * <?php * * xp_signal(XP_SIG('foo'), function(){ * echo 'foo'; * }); * * xp_after(XP_SIG('foo'), function(){ * echo 'after foo'; * }); * * The above code will output. * * .. code-block:: php * * // fooafter foo */ function xp_after($signal, $process) { if (!$signal instanceof \XPSPL\SIG) { $signal = new \XPSPL\SIG($signal); } if (!$process instanceof \XPSPL\Process) { $process = new \XPSPL\Process($process); } return XPSPL::instance()->after($signal, $process); }
/** * Registers a process to execute when the given signal is emitted. * * .. note:: * * All processes by default have an exhaust of ``null``. * * .. note:: * * Processes installed to the same signal execute in FIFO order * when no priority is defined. * * @param object $signal Signal to install process on. * @param object $callable PHP Callable * * @return object | boolean - \XPSPL\Process otherwise boolean on error * * .. note:: * * Beginning in XPSPL v4.0.0 all signals were converted to strictly objects. * * To use a string or integer as a signal it must be wrapped in a ``XP_SIG``. * * .. warning:: * * Any signal created using ```XP_SIG``` CANNOT be unique. * * @example * * Example #1 Basic Usage * * .. code-block:: php * * <?php * * // Install a process on the foo signal * xp_signal(XP_SIG('foo'), function(){ * echo 'foo'; * }); * * // Emit the foo signal * xp_emit(XP_SIG('foo')); * * The above example will output. * * .. code-block:: php * * foo * * @example * * Example #2 Class Signals * * .. code-block:: php * * <?php * * // Declare a simple signal * class SIG_Basic extends \XPSPL\SIG {} * * // Install a process on the SIG_Basic class * xp_signal(new SIG_Basic(), function(){ * echo 'foo'; * }) * * xp_emit(new SIG_Basic()); * * The above example will output. * * .. code-block:: php * * foo * * @example * * Example #3 Exhausting Processes * * .. code-block:: php * * <?php * * // Install a process on the foo signal, with an exhaust of 1 * xp_signal(XP_SIG('foo', xp_exhaust(1, function(){ * echo 'foo'; * }))); * * // Emit the foo signal * xp_emit(XP_SIG('foo')); * xp_emit(XP_SIG('foo')); * * The above code will output. * * .. code-block:: php * * foo * * @example * * Example #4 Unique Signals * * .. code-block:: php * * <?php * * // Declare a simple unique * class SIG_Foo extends \XPSPL\SIG { * // Set the signal as unique * protected $_unqiue = true; * } * * // Create two unique SIG_Foo objects * $sig_foo_1 = new SIG_Foo(); * $sig_foo_2 = new SIG_Foo(); * * // Install a process to each unique signal * xp_signal($sig_foo_1, function(){ * echo 'foo'; * }); * * xp_signal($sig_foo_2, function(){ * echo 'bar'; * }) * * // Emit each unique signal * xp_emit($sig_foo_1); * xp_emit($sig_foo_2); * * The above code will output. * * .. code-block:: php * * foobar */ function xp_signal(\XPSPL\SIG $signal, $process) { if (!$process instanceof \XPSPL\Process) { $process = new \XPSPL\Process($process); } return XPSPL::instance()->signal($signal, $process); }
/** * Returns the current signal history. * * The returned history is stored in an array using the following indexes. * * .. code-block:: php * * <?php * $array = [ * 0 => Signal Object * 1 => UNIX timestamp of execution * ]; * * @return array * * @example * * Example #1 Basic Usage * * Count the number of ``XP_SIG('foo')`` signals that were emitted. * * .. code-block:: php * * <?php * $sig = XP_SIG('foo'); * // Emit a few foo objects * for($i=0;$i<5;$i++){ * xp_emit($sig); * } * $emitted = 0; * foreach(xp_signal_history() as $_node) { * if ($_node[0] instanceof $sig) { * $emitted++; * } * } * echo $emitted; * * The above code will output. * * .. code-block:: php * * 5 */ function xp_signal_history() { return XPSPL::instance()->signal_history(); }
/** * Deletes an installed signal process. * * .. note:: * * The \\XPSPL\\Process object given must be the same returned or created * when the process was installed. * * @param object $signal \\XPSPL\\SIG signal to remove process from. * @param object $process \\XPSPL\\Process object to remove. * * @return void * * @example * * Example #1 Basic Usage * * .. code-block::php * * <?php * // Create a new process on the foo SIG. * $process_one = xp_signal(XP_SIG('foo'), function(){ * echo 'foo'; * }); * * $process_two = xp_signal(XP_SIG('foo'), function(){ * echo 'bar'; * }); * * // Delete process_one using the returned \XPSPL\Process object * xp_delete_process(XP_SIG('foo'), $process_one); * * // Emit foo * xp_emit(XP_SIG('foo')); * * The above code will output. * * .. code-block:: php * * bar */ function xp_delete_process($signal, $process) { return XPSPL::instance()->delete_process($signal, $process); }
/** * Registers a signal in the processor. * * @param string|integer|object $signal Signal * * @return object Database */ function xp_register_signal($signal) { return XPSPL::instance()->register_signal($signal); }
/** * Retrieve the current signal in execution. * * @param integer $offset If a positive offset is given it will return from * the top of the signal stack, if negative it will * return from the bottom (current) of the stack. * * @return object \\XPSPL\\SIG * * @example * * Example #1 Basic Usage * * .. code-block:: php * * <?php * * xp_signal(XP_SIG('foo'), function(\XPSPL\SIG $signal){ * $a = xp_current_signal(); * echo $a->get_index(); * }); * * The above code will output. * * .. code-block:: php * * foo * * @example * * Example #2 Parent Signals * * Parent signals can be fetched by using a negative offset ``< -1``. * * .. code-block:: php * * <?php * * // Install a process on the bar SIG * xp_signal(XP_SIG('bar'), function(){ * // Emit foo within bar * xp_emit(XP_SIG('foo')); * }); * * // Install a process on the foo SIG * xp_signal(XP_SIG('foo'), function(){ * // Get the parent of foo * $a = xp_current_signal(-2); * echo $a->get_index(); * }); * * The above code will output. * * .. code-block:: php * * bar */ function xp_current_signal($offset = 0) { return XPSPL::instance()->current_signal($offset); }
/** * Emits a signal. * * This will execute all processes, before and after functions installed to the * signal. * * Returns the executed ``\XPSPL\SIG`` object. * * .. note:: * * When emitting unique signals, e.g.. complex, routines or defined uniques * the unique ``\XPSPL\SIG`` object installed must be provided. * * Once a signal is emitted the following execution chain takes place. * * 1. Before process functions * 2. Process function * 3. After process function * * @param signal $signal \XPSPL\SIG object to emit. * @param object $context \XPSPL\SIG object context to execute within. * * @return object \XPSPL\SIG * * @example * * Example #1 Basic Usage * * .. code-block:: php * * <?php * * // Install a process on the foo signal * xp_signal(XP_SIG('foo'), function(){ * echo 'foo'; * }); * * // Emit the foo signal * xp_emit(XP_SIG('foo')); * * The above example will output. * * .. code-block:: php * * foo * * @example * * Example #2 Unique Signals * * .. code-block:: php * * <?php * * // Create a unique Foo signal. * class SIG_Foo extends \XPSPL\SIG { * // declare it as unique * protected $_unique = true; * } * * // Create a SIG_Foo unique object * $foo = new SIG_Foo(); * * signal($foo, function(){ * echo "foo"; * }); * * // Emit the SIG_Foo and another unique SIG_Foo * xp_emit($foo); * xp_emit(new Foo()); * * The above code will output. * * .. code-block:: php * * foo * * @example * * Example #3 Complex Signals * * .. code-block:: php * * <?php * * // Create our 3 required signals. * class SIG_Bells extends \XPSPL\SIG {} * class SIG_Bride extends \XPSPL\SIG {} * class SIG_Groom extends \XPSPL\SIG {} * * // Create a complex signal that will emit when a wedding takes place * // based on 3 seperate signals, SIG_Bells, SIG_Bride and SIG_Groom. * class SIG_Wedding extends \XPSPL\SIG_Complex { * * // Keep track if each requirement has already emitted * protected $_bells = false; * protected $_bride = false; * protected $_groom = false; * * // Create an evaulation method to evaluate the runtime * public function evaluate($signal = null) * { * switch ($signal) { * case $signal instanceof SIG_Bells: * $this->_bells = true; * break; * case $signal instanceof SIG_Bride: * $this->_bride = true; * break; * case $signal instanceof SIG_Groom: * $this->_groom = true; * break; * } * if ($this->_bells === true && * $this->_bride === true && * $this->_groom === true) { * $this->_bells = false; * $this->_groom = false; * $this->_bride = false; * return true; * } * return false; * } * } * * // Install a process for complex signal. * xp_signal(new SIG_Wedding(), function(){ * echo 'The wedding is happening!'.PHP_EOL; * }); * * // Emit SIG_Bells, SIG_Bride and SIG_Groom * xp_emit(new SIG_Bells()); * xp_emit(new SIG_Bride()); * xp_emit(new SIG_Groom()); * * The above code will output. * * .. code-block:: php * * The wedding is happening! */ function xp_emit($signal, $context = null) { if (!$signal instanceof \XPSPL\SIG) { $signal = new \XPSPL\SIG($signal); } return XPSPL::instance()->emit($signal, $context); }
/** * Sends the event loop the shutdown signal. * * @return void */ function xp_shutdown() { return XPSPL::instance()->shutdown(); }
/** * Erases the entire signal history. * * @return void * * @example * * Example #1 Basic Usage * * .. code-block:: php * * <?php * * // Create some history * xp_signal(XP_SIG('foo'), function(){}); * for ($i=0;$i<10;$i++) { * xp_emit(XP_SIG('foo')); * } * * // Dump the history count * var_dump(count(xp_signal_history())); * * // Erase the history * xp_erase_history(); * * var_dump(count(xp_signal_history())); * * The above code will output. * * .. code-block:: php * * 10 ... 0 */ function xp_erase_history() { return XPSPL::instance()->erase_history(); }
/** * Scans and removes non-emittable signals and processes. * * .. note:: * * This DOES NOT flush the processor. * * A signal is determined to be emittable only if it has installed processes * that have not exhausted. * * @param boolean $history Erase any history of removed signals. * * @return void * * @example * * Example #1 Basic Usage * * Basic usage example demonstrating cleaning old signals and processes. * * .. code-block:: php * * <?php * * xp_signal(XP_SIG('Test'), xp_exhaust(1, function(){ * echo 'SIG Test'; * })); * * xp_signal(XP_SIG('Test_2'), function(){ * echo 'SIG Test 2'; * }); * * xp_emit(XP_SIG('Test')); * * xp_clean(); * var_dump(xp_find_signal(XP_SIG('Test'))); * * The above code will output. * * .. code-block:: php * * SIG Test null */ function xp_clean($history = false) { return XPSPL::instance()->clean($history); }
/** * Delete a signal from the processor. * * @param string|object|int $signal Signal to delete. * @param boolean $history Erase any history of the signal. * * @return boolean * * @example * * Example #1 Basic Usage * * .. code-block:: php * * <?php * // Install process on signal foo * xp_signal(XP_SIG('foo'), function(){}); * // Delete the signal foo * xp_delete_signal(XP_SIG('foo')); * // Emit the signal foo * xp_emit(XP_SIG('foo')); */ function xp_delete_signal($signal, $history = false) { return XPSPL::instance()->delete_signal($signal, $history); }
/** * Registers a new listener. * * Listeners are special objects that register each publically available * method as an executing process using the method name. * * .. note:: * * Public methods that are declared with a prepended underscore "_" are * ignored. * * @param object $listener The object to register. * * @return void * * @example * * Example #1 Basic Usage * * .. code-block:: php * * <?php * * class My_Listener extends \XPSPL\Listener * { * // Register a process for the foo signal. * public function foobar($signal) { * echo 'foobar'; * } * } * * xp_listener(new My_Listener()); * * xp_emit(XP_SIG('foobar')); * * The above code will output. * * .. code-block:: php * * foobar */ function xp_listen($listener) { return XPSPL::instance()->listen($listener); }
/** * Sets the flag for storing the event history. * * @param boolean $flag * * @return void */ function xp_set_signal_history($flag) { return XPSPL::instance()->set_signal_history($flag); }
/** * Returns the global XPSPL processor. * * @return object XPSPL\Processor */ function XPSPL() { return XPSPL::instance(); }
/** * Begins the XPSPL event wait loop. * * The event loop must be started to allow execution of time, networking or * complex loop based signals. * * .. note:: * * XPSPL provides an executable ``xpspl`` in the *bin* directory for * automatically loading code into the event loop. * * .. warning:: * * This is a *BLOCKING* function. * * Any code underneath the function call will *NOT* be executed until * the processor halts execution. * * @return void * * @example * * Example #1 Basic Usage * * Basic usage example demonstrating using the loop for time based code. * * .. code-block:: php * * <?php * * // Import time module * xp_import('time'); * * xp_time\awake(10, function(){ * echo '10 seconds passed'; * }); * * xp_wait_loop(); * * @example * * Automatic shutdown * * The processor loop has built in support for automatically shutting down when * it detects there is nothing else it will ever do. * * This example demonstrates the loop shutting down after emitting 5 time based * signals. * * .. code-block:: php * */ function xp_wait_loop() { return XPSPL::instance()->wait_loop(); }
/** * Erases the history of only the given signal. * * .. warning:: * * This will delete the history for *ANY* signals that are a direct child of * the to be deleted signal. * * As an example, * * When ``sig_foo`` emits it is proceeded directly by ``sig_foo2`` emitting * within the ``sig_foo`` execution. * * When sig_foo is deleted the history of sig_foo_child will also be removed. * * @param string|object $signal Signal to be erased from history. * * @return void * * @example * * Example #1 Basic Usage * * .. code-block:: php * * <?php * * // Install a procss for the foo and bar signals. * xp_signal(XP_SIG('foo'), function(){}); * xp_signal(XP_SIG('bar'), function(){}); * // Emit each foo and bar 10 times. * for($i=0;$i<10;$i++) { * xp_emit(XP_SIG('foo')); * xp_emit(XP_SIG('bar')); * } * var_dump(count(xp_signal_history())); * // Delete the history of the foo signal. * xp_delete_signal_history(XP_SIG('foo')); * var_dump(count(xp_signal_history())); * * The above code will output. * * .. code-block:: php * * 20 ... 10 */ function xp_erase_signal_history($signal) { return XPSPL::instance()->erase_signal_history($signal); }
/** * Performs a complete flush of the processor. * * This will clear the processor state and remove the following. * * * Installed signals. * * Installed processes. * * Signal history. * * @return void */ function XPSPL_flush() { return XPSPL::instance()->flush(); }