arara / process
Provides a better API to work with processes on Unix-like systems
Installs: 54 958
Dependents: 3
Suggesters: 1
Security: 0
Stars: 170
Watchers: 17
Forks: 15
Open Issues: 1
Requires
- php: >=5.4.0
- ext-pcntl: *
- ext-posix: *
- phpfluent/callback: ~1.0
Requires (Dev)
- ext-uopz: *
- phpmd/phpmd: ~2.2
- phpunit/phpunit: ~4.6
- squizlabs/php_codesniffer: ~2.3
README
This library provides a better API to work with processes on Unix-like systems using PHP.
Installation
The package is available on Packagist. You can install it using Composer.
composer require arara/process
Dependencies
- PHP 5.4+
- PCNTL
- POSIX
- PHPFluent\Callback (installed by Composer)
Version 1.6.0 or less of Arara\Process works on PHP 5.3.
Usage
Along with this document, there are many usage examples in the examples/ directory which may be used for reference.
All examples within this document assume you have the following statement at the beginning of the file:
declare(ticks=1);
Without this statement, there is no guarantee PHP will handle signals; this is very important for PCNTL to work properly. It has been required since version 4.3.0 of PHP, so this is not a request of the library but of the PHP language itself.
If you want to know more about ticks, we recommend you read http://php.net/declare#control-structures.declare.ticks.
Action interface
Forks may be encapsulated using Arara\Process\Action\Action
interface.
All classes that implements this interface must implement two methods:
execute(..)
: may contain the action performed in the backgroundtrigger(...)
: may contain specific actions to events
Using this interface you can create your own actions and run them in the background.
Events
The Arara\Process\Action\Action::trigger(..)
method, as it is written, associates specific actions with events.
Those events can be:
Action::EVENT_INIT
: triggered when action is initialized- When the action is attached to a Child object
Action::EVENT_FORK
: triggered when action is forked- After the action is forked it is triggered on the parent process
Action::EVENT_START
: triggered before the execute() method is executedAction::EVENT_SUCCESS
: triggered when the action is finished with success, that is:- When the action does not encounter a PHP error
- When the action does not throw an exception
- When the action does not return any value
- When the action returns an
Action::EVENT_SUCCESS
value
Action::EVENT_ERROR
: triggered when the action is encounters an error, that is:- When the action encounters a PHP error
- When the action returns an
Action:EVENT_ERROR
value
Action::EVENT_FAILURE
: triggered after the action has finished and failed, that is:- When the action throws an exception
- When the action returns an
Action::EVENT_FAILURE
value
Action::EVENT_TIMEOUT
: triggered when the action experiences a timeoutAction::EVENT_FINISH
: triggered after the execute() method has executed.
Callback action
In order to make it easy to execute forks with no need to create a specific class to execute something in the background, there is a generic implementation that allows a callback to be run in the background; the only thing one must do is pass the callback to the constructor of this class.
use Arara\Process\Action\Callback; $callback = new Callback(function () { echo "This will be executed in the background!" . PHP_EOL; });
The Callback action provides a way to bind callbacks to be triggered by specific events:
$callback->bind(Callback::EVENT_SUCCESS, function () { echo "This will be executed if the action callback was successful!" . PHP_EOL; });
Also, one can bind a callback to multiple events:
$callback->bind(Callback::EVENT_ERROR | Callback::EVENT_FAILURE, function () { echo "It is going to be executed if the action fails or get an error" . PHP_EOL; });
Command action
You may want to run just a Linux command, for that reason there is Command action.
$command = new Command('whoami');
Using Command action you can define arguments as second param:
$command = new Command('cp', array('/path/to/source', '/path/to/destination'));
If you prefer arguments can be defined by a key => value array:
$command = new Command( 'find', array( '/path/to/dir', '-name' => '*', '-type' => 'f', ) );
Command action is based on Callback action so you can also bind triggers for events.
Daemon action
You can create daemons using the Arara\Process\Action\Daemon
class:
$daemon = new Daemon( function (Control $control, Context $context, Daemon $daemon) { while (! $daemon->isDying()) { // Do whatever you want =) } } );
This action will:
- Detach process session from the parent
- Update process umask
- Update process work directory
- Define process GID (if defined)
- Define process UID (if defined)
- Recreate standards file descriptors (STDIN, STDOUT and STDERR)
- Create Pidfile
- Run the defined payload callback
Daemon action is based on Callback action thus you can also bind triggers for events.
Daemon options
Daemon action class has some options that allows you to change some behaviours:
name
: Name used by pidfile (default arara)lock_dir
: Lock directory for pidfile (default /var/run)work_dir
: Work directory (default /)umask
: Default umask value (default 0)user_id
: When defined changed the daemon UID (default NULL)group_id
: When defined changed the daemon GID (default NULL)stdin
: File to use asSTDIN
(default /dev/null)stdout
: File to use asSTDOUT
(default /dev/null)stderr
: File to use asSTDERR
(default /dev/null)
You can change default daemon options by defining it on class constructor:
$daemon = new Daemon( $callback, array( 'name' => 'mydaemonname', 'lock_dir' => __DIR__, ) );
After the object is created you may change all options:
$daemon->setOptions( array( 'stdout' => '/tmp/daemon.stdout', 'stderr' => '/tmp/daemon.stderr', ) );
Also you can change just an option:
$daemon->setOption('work_dir', __DIR__);
Starting a process in the background
The class Arara\Process\Child
allows you to execute any action in the background.
$child = new Child( new Daemon(function () { // What my daemon does... }), new Control() ); $child->start(); // Runs the callback in the background
The above example runs the Daemon action in the background, but one can use any class which implements
the Arara\Process\Action\Action
interface like Callback action.
Check if the process is running
Checking to see if a process is running is a very common routine; to perform this using this library you may call:
$child->isRunning(); // Returns TRUE if it is running or FALSE if it is not
This method not only checks the state of the object, but also checks to see if the process is already running on the system.
Terminating the process
If the process has already started, this tells the process to terminate, but does not force it.
$child->terminate(); // Sends a SIGTERM to the process
Killing the process
If it has already started, this forces the process to terminate immediately.
$child->kill(); // Sends a SIGKILL to the process
Waiting on the process
If you want to wait on the process to finish, instead of just starting the process in the background, you can call:
$child->wait();
The next line of code will be executed after the process finishes.
Getting a process' status
It is possible to get the status of a process after waiting for it finish.
The Arara\Process\Child
class has a method getStatus()
which allows you to check the status of a process.
$child->getStatus(); // Returns an Arara\Process\Control\Status instance
Internally, this calls the wait()
method, in order to wait for the process to finish - and then get its status.
Get the exit code of the process
$child->getStatus()->getExitStatus();
Get the signal which caused the process to stop
$child->getStatus()->getStopSignal();
Get the signal which caused the process to terminate
$child->getStatus()->getTerminateSignal();
Checks if the status code represents a normal exit
$child->getStatus()->isExited();
Checks whether the status code represents a termination due to a signal
$child->getStatus()->isSignaled();
Checks whether the process is stopped
$child->getStatus()->isStopped();
Checks if the process was finished successfully
$child->getStatus()->isSuccessful();
Spawning
Since you are working with forks you are able work with spawn as well. The Arara\Process\Pool
class provides a simple
way to work with it.
This class handles the queue of process dynamically, the only thing you have to do is provide the limit of children you want in the constructor and then attach the children.
$maxConcurrentChildren = 2; $pool = new Pool($maxConcurrentChildren); $pool->start(); $pool->attach(new Child(/* ... */)); $pool->attach(new Child(/* ... */)); $pool->attach(new Child(/* ... */)); $pool->attach(new Child(/* ... */)); // ...
The number of children it has does not matter; it will only run 2 process simultaneously; when one of those process is finished, it is removed from the queue and a new slot is opened.
The Arara\Process\Pool
class contains most of the methods of Arara\Process\Child
class:
isRunning()
kill()
start()
terminate()
wait()
This behaves similarly for all methods.
Control class
You can also handle processes without using Pool, Child or the Action classes.
We provide a simple API to work with the pcntl_*
and posix_*
functions. You can learn more by reading the
code of Arara\Process\Control
and its dependencies, but here is an example:
$control = new Control(); $pid = $control->fork();// Throws RuntimeException when pcntl_fork() returns -1 if ($pid > 0) { echo 'Waiting on child...' . PHP_EOL; $control->waitProcessId($pid); echo 'Child finished' . PHP_EOL; $control->quit(); } echo 'Child process has PID ' . $control->info()->getId() . PHP_EOL; echo 'Child process has parent PID ' . $control->info()->getParentId() . PHP_EOL; $control->flush(2.5); // Will try to flush current process memory and sleep by 2 and a half seconds $control->signal()->send('kill'); // Will send SIGKILL to the current process (the child)
Pidfile class
If you are working with background tasks you may want to create a lock to avoid people running your script twice. For this
purpose there is the class Arara\Process\Pidfile
.
$control = new Control(); $applicationName = 'my_app'; $pidfile = new Pidfile($control, $applicationName); $pidfile->initialize(); // Whatever you need here... $pidfile->finalize();
The second time someone runs it an exception is thrown. We recommend you put this code into a try..catch
statement.