xpspl Documentation · xpspl Documentation, Release 4.0.0 XPSPL is a high performance signal...

xpspl DocumentationRelease 4.0.0

Nickolas Whiting

January 18, 2014

Contents

i

xpspl Documentation, Release 4.0.0

XPSPL is a high performance signal processor for the PHP programming language.

Contents 1


2 Contents

CHAPTER 1

Table of Contents

1.1 Installing XPSPL

1.1.1 Requirements

XPSPL requires >= PHP 5.4.

XPSPL does not require any additional modules or configuration options.

1.1.2 Install

XPSPL installation is over the network with a CLI. (link)

The installation requires the CURL and ZIP libraries to be installed on the system.

curl -s https://raw.github.com/prggmr/xpspl/master/install | sudo sh

Once installed the xpspl command becomes available.

1.1.3 Updates

Peform updates by running xpspl with option --update.

xpspl --update

1.1.4 Optional

C Judy 1.0.4 PECL Judy 0.1.4

The Judy library demonstrates improving the database by giving storage a linear scale of ~39us up to the tested 262144.

The Judy C library is bundled in the library folder with XPSPL.

For installation of Judy C see the README.

For installation of Judy PECL visit here.

1.1.5 Windows

Currently a Windows installation guide does not exist.

3

https://raw.github.com/prggmr/xpspl/master/install

http://pecl.php.net/package/Judy


1.2 Configuration

Configuration values are defined using constants before loading XPSPL.

1.2.1 Constants

XPSPL_DEBUG

XPSPL Debug mode

When turned on XPSPL generates a log of all activity to STDOUT.

When turned off XPSPL removes its processor traces from uncaught exceptions.

XPSPL_SIGNAL_HISTORY

Signal History

Default setting for the saving the signal history.

By default this is false.

XPSPL_PURGE_EXHAUSTED

Remove Exhausted processes

When turned on this automatically removes installed processes from the processor once it determines they can nolonger be used.

By default this settings is true.

XPSPL_MODULE_DIR

Module Directory

Directory to look for modules.

By default it is set to the module directory in XPSPL.

XPSPL_PROCESS_DEFAULT_EXHAUST

Default process exhaustion

Integer option defining the default exhausting of a process.

By default it is 1.

XPSPL_PROCESS_DEFAULT_PRIORITY

Process default priority

Integer option defining the default priority of all processes.

By default it is 10.

4 Chapter 1. Table of Contents


XPSPL_JUDY_SUPPORT

Judy is an optional database configuration.

http://xpspl.prggmr.org/en/xspel/install.html#optional

Currently this is experimental as an attempt to improve performance.

Once stable this will automatically be enabled if Judy is detected.

XPSPL_ANALYZE_TIME

UNUSED

This is an unused configuration option that will later add support for analyzing the processor timing to auto correctsignal timing ... at least that is the theory.

Last updated on 04/23/13 11:50pm

1.2. Configuration 5

http://xpspl.prggmr.org/en/xspel/install.html#optional


6 Chapter 1. Table of Contents

CHAPTER 2

API

All API functions are non-namespaced, globally available.

2.1 Function - after

after($signal, $process)Installs the given process to interrupt the signal $signal when emitted.

Interruption processes installed using this function interrupt directly after a signal is emitted.

Warning: Interruptions are not a fix for improperly executing process priorities within a signal.If unexpected process priority are being executed debug them...

Note: Interruptions use the same prioritizing as the Processor.

Parameters callable|process – PHP Callable or XPSPLProcess.

Return type object Process

2.1.1 Install a interrupt process after foo

High priority process will always execute first immediatly following interruptions.

<?php

signal(SIG(’foo’), function(){echo ’foo’;

});

after(SIG(’foo’), function(){echo ’after foo’;

});

// results when foo is emitted// fooafter foo

7


2.1.2 After Interrupt Process Priority

Install after interrupt processes with priority.

<?phpsignal(SIG(’foo’), function(){

echo ’foo’;})

after(SIG(’foo’), low_priority(function(){echo ’low priority foo’;

}));

after(SIG(’foo’), high_priority(function(){echo ’high priority foo’;

}));

emit(SIG(’foo’));

// results// foo highpriorityfoo lowpriorityfoo


2.2 Function - before

before($signal, $process)Installs the given process to interrupt the signal $signal when emitted.

Interruption processes installed using this function interrupt directly after a signal is emitted.

Warning: Interruptions are not a fix for improperly executing process priorities within a signal.If unexpected process priority are being executed debug them...

Note: Interruptions use the same prioritizing as the Processor.



2.2.1 Install a interrupt process before foo

High priority process will always execute first immediatly following interruptions.

<?php

signal(SIG(’foo’), function(){echo ’foo’;

});

before(SIG(’foo’), function(){echo ’before foo’;

});

8 Chapter 2. API


// results when foo is emitted// foobefore foo

2.2.2 Before Interrupt Process Priority

Install before interrupt processes with priority.


echo ’foo’;})

before(SIG(’foo’), low_priority(function(){echo ’low priority foo’;

}));

before(SIG(’foo’), high_priority(function(){echo ’high priority foo’;

}));


// results// highpriorityfoo lowpriorityfoo foo


2.3 Function - clean

clean([$history = false])Cleans any exhausted signals from the processor.

Parameters boolean – Also erase any history of the signals cleaned.

Return type void


2.4 Function - current_signal

current_signal([$offset = false])Returns the current signal in execution.

Parameters integer – In memory hierarchy offset +/-.

Return type object


2.3. Function - clean 9


2.5 Function - delete_process

delete_process($signal, $process)Removes an installed signal process.

Parameters

• string|integer|object – Signal process is attached to.

• object – Process.

Return type void

2.5.1 Removing installed processes

Removes the installed process from the foo signal.


2.6 Function - delete_signal

delete_signal($signal[, $history = false])Delete a signal from the processor.

Parameters

• string|object|int – Signal to delete.

• boolean – Erase any history of the signal.

Return type boolean


2.7 Function - dir_include

dir_include($dir[, $listen = false[, $path = false]])Performs a inclusion of the entire directory content, including subdirectories, with the option to start a listeneronce the file has been included.

Parameters

• string – Directory to include.

• boolean – Start listeners.

• string – Path to ignore when starting listeners.

Return type void


10 Chapter 2. API


2.8 Function - emit

emit($signal[, $context = false])Emit a signal.

This will execute all processes and interruptions installed to the signal.

The executed SIG object is returned.

Note: When emitting unique signals, e.g.. complex, routines or defined uniques the unique sig object installedmust be given.

Once a signal is emitted the following execution chain takes place.

1.Before process interruptions

2.Installed processes

3.After process interruptions

Parameters

• signal – Signal to emit.

• object – Signal context.

Return type object SIG

2.8.1 Emitting a unique signal

When a unique signal is emitted

<?php// Create a unique Foo signal.class Foo extends \XPSPL\SIG {

// declare it as uniqueprotected $_unique = true;

}// Install a null exhaust process for the Foo signal$foo = new Foo();signal($foo, null_exhaust(function(){

echo "Foo";}));// Emit foo and new Fooemit($foo);emit(new Foo());// Results// Foo


2.9 Function - erase_history

erase_history()Cleans out the entire signal history.

Return type void

2.8. Function - emit 11



2.10 Function - erase_signal_history

erase_signal_history($signal)Erases any history of a signal.

Parameters string|object – Signal to be erased from history.

Return type void


2.11 Function - exhaust

exhaust($limit, $process)Registers the given process to have the given exhaust rate.

A rated exhaust allows for you to install processes that exhaust at the set rate rather than 1.

If you require a null exhaust process use the null_exhaust function.

Parameters callable|process – PHP Callable or Process.


2.11.1 Defining process exhaust.

Defines the given process with an exhaust of 5.

<?php

signal(SIG(’foo’), exhaust(5, function(){echo ’foo’;

});

for($i=0;$i<5;$i++){emit(’foo’);

}

// results// foofoofoofoofoo

2.11.2 Null exhaust process.

Install a process that never exhausts.

Note: Once a null exhaust process is installed it must be removed using delete_process.

<?php

signal(SIG(’foo’), null_exhaust(function(){echo "foo";

12 Chapter 2. API


}));

for ($i=0;$i<35;$i++) {emit(SIG(’foo’));

}// results// foo// foo// foo// foo// ...


2.12 Function - find_signal_database

find_signal_database($signal)Finds an installed signals processes database.

Parameters object – SIG

Return type null|object XPSPLdatabaseSignals


2.13 Function - high_priority

high_priority($process)Registers the given process to have a high priority.

Processes registered with a high priority will be executed before those with a low or default priority.

This allows for controlling the order of processes rather than using FIFO.

A high priority process is useful when multiple processes will execute and it must always be one of the very firstto run.

This registers the priority as 0.

Note: This is not an interruption.

Installed interruptions will still be executed before a high priority process.



2.13.1 Install a process with high priority

High priority process will always execute first.

<?php

signal(’foo’, function(){echo ’bar’;

2.12. Function - find_signal_database 13


});

signal(’foo’, high_priority(function(){echo ’foo’;

}));

// results when foo is emitted// foobar


2.14 Function - import

import($name[, $dir = false])Import a module.

Parameters

• string – Module name.

• string|null – Location of the module.

Return type void


2.15 Function - listen

listen($listener)Registers a new event listener object in the processor.

Parameters object – The event listening object

Return type void


2.16 Function - low_priority

low_priority($process)Registers the given process to have a low priority.

Processes registered with a low priority will be executed after those with a high and default priority.


A low priority process is useful when multiple processes will execute and it must always be one of the very lastto run.

This registers the priority as PHP_INT_MAX.


Installed interruptions will still be executed after a low priority process.

14 Chapter 2. API




2.16.1 Install a process with low priority

Low priority processes always execute last.

<?php

signal(’foo’, function(){echo ’foo’;

});

signal(’foo’, low_priority(function(){echo ’bar’;

}));

// results when foo is emitted// foobar


2.17 Function - null_exhaust

null_exhaust($process)Registers the given process to have a null exhaust.

Be careful when registering a null exhaust process.

Once registered it will never be purged from the processor.

Do not register a null exhaust process unless you are absolutely sure you want it to never exhaust.

If you require a process to exhaust after a few executions use the rated_exhaust function.

Parameters callable|process – PHP Callable or Process.


2.17.1 Install a null exhaust process.

This example installs a null exhaust process which calls an awake signal every 10 seconds creating an interval.

<?phpimport(’time’);

time\awake(10, null_exhaust(function(){echo "10 seconds";

}));


2.17. Function - null_exhaust 15


2.18 Function - on_shutdown

on_shutdown($function)Call the provided function on processor shutdown.

Parameters callable|object – Function or process object

Return type object XPSPLProcess


2.19 Function - on_start

on_start($function)Call the provided function on processor start.

Parameters callable|object – Function or process object

Return type object XPSPLProcess


2.20 Function - priority

priority($priority, $process)Registers the given process to have the given priority.


Priority uses an ascending order where 0 > 1.

Processes registered with a high priority will be executed before those with a low or default priority.

Process priority is handy when multiple process will execute and their order is important.


Installed interruptions will still be executed before or after a prioritized process.

Parameters

• integer – Priority to assign

• callable|process – PHP Callable or XPSPLProcess.


2.20.1 Installing multiple priorities

This installs multiple process each with a seperate ascending priority.

<?php

signal(’foo’, priority(0, function(){echo ’foo’;

}));

16 Chapter 2. API


signal(’foo’, priority(3, function(){echo ’bar’;

}));

signal(’foo’, priority(5, function(){echo ’hello’;

}));

signal(’foo’, priority(10, function(){echo ’world’;

}));

// results when foo is emitted// foobarhelloworld


2.21 Function - process

process($callable)Creates a new XPSPL Process object.

Note: See the priority and exhaust functions for setting the priority and exhaust of the created process.

Parameters callable –

Return type void

2.21.1 Creates a new XPSPL Process object.


2.22 Function - register_signal

register_signal($signal)Registers a signal in the processor.

Parameters string|integer|object – Signal

Return type object Database


2.23 Function - set_signal_history

set_signal_history($flag)Sets the flag for storing the event history.

Parameters boolean –

Return type void

2.21. Function - process 17



2.24 Function - shutdown

shutdown()Sends the loop the shutdown signal.

Return type void


2.25 Function - SIG

SIG($signal)Generates an XPSPL SIG object from the given $signal.

This function is only a shorthand for new SIG($signal).

Parameters string| – Signal process is attached to.

Return type object XPSPLSIG

2.25.1 Creating a SIG.

This will create a SIG idenitified by ‘foo’.


echo "HelloWorld";});



2.26 Function - signal

signal($signal, $process)Installs a new process to execute when the given signal is emitted.

Note: All processes unless otherwise specified have a default exhaust of XPSPL_EXHAUST_DEFAULT.

Note: Processes installed to the same signal execute in FIFO order without priority.

Parameters

• object – Signal to install process on.

• object – PHP Callable

Return type object | boolean - XPSPLProcess otherwise boolean on error

18 Chapter 2. API


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 SIG.

Note: Any signals wrapped in SIG cannot be unique.

2.26.1 Install a new process.

This demonstrates installing a new process to execute on SIG(foo).


echo "foo was emitted";});

emit(’foo’);

Results

foo was emitted

2.26.2 String or Integer signals

When using strings or integers as a signal the string or integer must be wrapped in the SIG function.

<?php// install a process for foosignal(’foo’, function(){

echo ’foo’;});// emit fooemit(’foo’);// results// foo


2.27 Function - signal_history

signal_history()Returns the current signal history.

The returned history is stored in an array using the following indexes.

<?php$array = [

0 => Signal Object1 => Time in microseconds since Epoch at emittion

];

Return type array

2.27. Function - signal_history 19


2.27.1 Counting emitted signals

This counts the number of SIG(’foo’) signals that were emitted.

<?php$sig = SIG(’foo’);// Emit a few foo objectsfor($i=0;$i<5;$i++){

emit($sig);}$emitted = 0;foreach(signal_history() as $_node) {

if ($_node[0] instanceof $sig) {$emitted++;

}}echo $emitted;


2.28 Function - wait_loop

wait_loop()Starts the XPSPL wait loop.

Return type void


2.29 Function - XPSPL

XPSPL()Returns the XPSPL processor.

Return type object XPSPLProcessor


2.30 Function - XPSPL_flush

XPSPL_flush()Empties the storage, history and clears the current state.

Return type void


20 Chapter 2. API

CHAPTER 3

Modules

XPSPL Bundled modules.

3.1 FTP Module

The FTP Module provides Non-Blocking FTP transfers for XPSPL.

Note: Currently only uploading files to a remote server is supported.

3.1.1 Installation

The FTP Module is bundled with XPSPL as of version 3.0.0.

Requirements

PHP

PHP FTP extension must be installed and enabled.

XPSPL

XPSPL >= 3.0

3.1.2 Configuration

The FTP Module has no runtime configuration options available.

3.1.3 Usage

Importing

21

http://php.net/manual/en/book.ftp.php


<?php

import(’ftp’);

Uploading Files

<?php

import(’ftp’);

$files = [’/tmp/myfile_1.txt’, ’/tmp/myfile_2.txt’];$server = [

’hostname’ => ’ftp.myhost.com’,’username’ => ’foo’,’password’ => ’bar’

];

$upload = ftp\upload($files, $server);

ftp\complete($upload, null_exhaust(function(){$file = $this->get_file();echo sprintf(’%s has uploaded’.PHP_EOL,

$file->get_name());

}));

ftp\failure($upload, null_exhaust(function(){$file = $this->get_file();echo sprintf(’%s has failed to upload’.PHP_EOL,

$file->get_name());

}));

3.1.4 API

All functions and classes are under the ftp namespace.

ftp\upload(array $files, array $connection, [callable $callback = null])Performs a non-blocking FTP upload of the given file(s).

When multiple files are given they will be uploaded simultaneously using separate connections to the given$connection.

The $callback will be called once the files begin uploading.

It is expected that the absolute path to the file will be given, failure to do so will cause unexpected behavior.

The connection array accepts,

•hostname - Hostname of the server to upload.

•username - Username to use when connecting.

•password - Password to use when connecting.

•port - Port number to connect on. Default=21

•timeout - Connection timeout in seconds. Default=90

22 Chapter 3. Modules


Parameters

• $files (array) – Files to upload

• $connection (array) – FTP Connection options

• $callback (callable) – Function to call when upload begins

Return object SIG_Upload

3.1. FTP Module 23


24 Chapter 3. Modules

CHAPTER 4

Source

XPSPL is hosted on Github.

25

https://github.com/prggmr/XPSPL


26 Chapter 4. Source

CHAPTER 5

Performance

These tests were generated using v4.0.0 on a 2.7GHZ i5 processor.

The above benchmark demonstrates scaling to an upperbound of 500 million emitted signals, the vertical axis repre-sents the amount of time in seconds with the horizontal axis representing the amount of signals emitted.

The benchmark demonstrates almost linear scale of ~3.5us per emit equating to ~284,000 signals per second.

27


28 Chapter 5. Performance

CHAPTER 6

Author

XPSPL has been designed and developed by Nickolas C. Whiting.

29


30 Chapter 6. Author

CHAPTER 7

Support

Support for XPSPL is offered through two support channels.

7.1 Mailing list

A mailing list provided by Google Groups.

7.2 IRC

An IRC channel by irc.freenode.net #prggmr.

31

https://groups.google.com/forum/?fromgroups#!forum/prggmr


32 Chapter 7. Support

CHAPTER 8

Search

• search

33

xpspl Documentation · xpspl Documentation, Release 4.0.0 XPSPL is a high performance signal...

Documents

Transcript of xpspl Documentation · xpspl Documentation, Release 4.0.0 XPSPL is a high performance signal...