/**
* 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);
}
/**
* 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);
}
/**
* 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();
}
/**
* 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);
}
/**
* Returns the global XPSPL processor.
*
* @return object XPSPL\Processor
*/
function XPSPL()
{
return XPSPL::instance();
}
/**
* 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 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();
}
*
* @param boolean $event_history Store a history of all events.
*
* @return object XPSPL\Processor
*/
public static final function init($event_history = true)
{
if (null === static::$_instance) {
static::$_instance = new self($event_history);
}
return static::$_instance;
}
/**
* Returns the current version of XPSPL.
*
* @return string
*/
public static final function version()
{
return XPSPL_VERSION;
}
}
/**
* Thats right ... that says global.
*/
global $XPSPL;
/**
* Start the processor VROOOOOOM!
*/
$XPSPL = XPSPL::init(XPSPL_SIGNAL_HISTORY);
/**
* 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);
}
/**
* Sends the event loop the shutdown signal.
*
* @return void
*/
function xp_shutdown()
{
return XPSPL::instance()->shutdown();
}
/**
* 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();
}
