eclipxe/php-soft-daemon

PHP Library to wait for system signals and running code

eclipxe/php-soft-daemon

![Source Code][badge-source] ![Latest Version][badge-release] [![Build Status][badge-build]][build] ![Coverage Status][badge-coverage] , _(*1)

PHP SoftDaemon Library

SoftDaemon provides a library to run continuously some code., _(*2)

I create this library to execute procedures continuously and to manipulate the time between iterations. I also use it to send signals to the processes in order to manipulate the behavior of the execution., _(*3)

Do not reinvent the wheel, if cron jobs are suitable to you then use them., _(*4)

How it runs

You have to create an instance of SoftDaemon, it requires minimum an Executable object that implements SoftDaemon\Executable interface, _(*5)

The SoftDaemon\Executable interface requires that you create two methods:, _(*6)

• Will call signalHandler(int $signo): void to optionally do something with the signal.
• Will call runOnce(): bool on each iteration.

For example, you can use signalHandler($signo) to process SIGHUP., _(*7)

Once you have instantiated a SoftDaemon object you can call the method run(). This method will enter into a loop and run Executable::runOnce() on every iteration. At the end on every iteration the loop will wait., _(*8)

Signals used

These signals are catched by SoftDaemon. All signals pass to Executable::signalHandler($signo) before `SoftDaemon do its own processing., _(*9)

• SIGHUP: Reset the error counter to zero. Method: SoftDaemon::resetErrorCounter()
• SIGUSR1: Pause iterations. Method: SoftDaemon::setPause(true)
• SIGUSR2: Unpause iterations. Method: SoftDaemon::setPause(false)
• SIGTERM, SIGINT, SIGQUIT: Terminate the iterations. Method: SoftDaemon::terminate()

How SoftDaemon knows how many seconds will wait

The pause state determines the quantity of seconds to wait for signals and continue to the next iteration., _(*10)

If the SoftDaemon is on pause then it will not call runOnce, it will only try to wait 1 second., _(*11)

If not on pause then it will use the counter of errors and request the sequencer to determine the number of seconds to wait., _(*12)

The result of Executable::runOnce(): bool determines the number of errors. It is reset to zero when runOnce() returns true. It is increased by 1 when runOnce() returns false., _(*13)

Anyhow, the number of seconds will be bounded to MinWait and MaxWait properties., _(*14)

About sequencers

A sequencer is an objects that implements SoftDaemon\Sequencer. Its purpose is to receive the number of errors and return a quantity of seconds to wait. There are some predefined Sequencers already defined in the namespace SoftDaemon\Sequencer:, _(*15)

• Fixed: It always returns the same quantity of seconds.
• Linear: It returns the quantity of seconds as the count of errors (0 -> 0, 1 -> 1, 2 -> 2, ...).
• Exponential: It returns the quantity of seconds as the count of errors to an exponential minus 1, if the base is 2 then it will return the following numbers: (0 -> 0, 1 -> 1, 2 -> 3, 3 -> 7, 4 -> 15, ...).

You can create a sequencer with your own rules. The MinWait and MaxWait limit the boundaries of seconds returned by the sequencer., _(*16)

PHP Support

This library is compatible with at least the oldest PHP Supported Version with active support. Please, try to use PHP full potential., _(*17)

We adhere to Semantic Versioning. We will not introduce any compatibility backwards change on major versions., _(*18)

Internal classes (using @internal annotation) are not part of this agreement as they must only exist inside this project. Do not use them in your project., _(*19)

Contributing

Contributions are welcome! Please read CONTRIBUTING for details and don't forget to take a look the TODO and CHANGELOG files., _(*20)

Copyright and License

The eclipxe/php-soft-daemon library is copyright © Carlos C Soto and licensed for use under the MIT License (MIT). Please see LICENSE for more information., _(*21)