GPhpThread
in package
A heavy thread creation and manipulation class.
Provides purely implemented in php instruments for "thread" creation and manipulation. A shell access, pcntl, posix, linux OS and PHP 5.3+ are required.
Table of Contents
Methods
- __construct() : mixed
- Constructor.
- __destruct() : mixed
- Destructor (default). It will not be called in the heavy thread if thread exit codes are disabled!
- BGN_HIGH_PRIOR_EXEC_BLOCK() : void
- Marks the start of a code block with high execution priority.
- END_HIGH_PRIOR_EXEC_BLOCK() : void
- Marks the end of a code block with high execution priority.
- getExitCode() : int
- Returns the thread's exit code.
- getPid() : int|bool
- Returns the current thread's (process) id.
- getPriority() : int|bool
- Returns the current execution priority of the thread.
- isAlive() : bool
- Checks if the thread is alive.
- isInGPhpThread() : null|bool
- Execution protector. Recommended to be used everywhere where execution is not desired.
- isParentAlive() : bool
- Checks if the creator of the heavy thread is alive.
- join() : bool
- Waits for executing thread to return.
- pause() : bool
- Pauses the execution of the thread.
- resetThreadIdGenerator() : void
- Resets the internal thread id generator. This can be used to allow creation of threads from another thread.
- resume() : bool
- Resumes the execution of a paused thread.
- run() : void
- Abstract method, the entry point of a particular GPhpThread inheritor implementation.
- setPriority() : bool
- Sets the execution priority of the thread. A super user privileges are required.
- start() : bool
- Starts the thread.
- stop() : bool
- Stops executing thread.
- makeNicer() : bool
- At process level decreases the niceness of a heavy "thread" making its priority higher. Multiple calls of the method will accumulate and increase the effect.
- makeUnfriendlier() : bool
- At process level increases the niceness of a heavy "thread" making its priority lower. Multiple calls of the method will accumulate and increase the effect.
- milliSleep() : bool
- Suspends the thread execution for a specific amount of milliseconds, redirecting the CPU resources to somewhere else.
- setExitCode() : void
- Specifies the running thread's exit code when it terminates.
- sleep() : bool
- Suspends the thread execution for a specific amount of time, redirecting the CPU resources to somewhere else. The total delay is the sum of all passed parameters.
- amIParent() : bool
- Returns if the current process is a parent (has created thread).
- notifyParentThatChildIsTerminated() : void
- Notifies the parent of the current thread that the thread has exited.
Methods
__construct()
Constructor.
public
__construct(GPhpThreadCriticalSection|null &$criticalSection, bool $allowThreadExitCodes) : mixed
Parameters
- $criticalSection : GPhpThreadCriticalSection|null
-
Instance of the critical section that is going to be associated with the created thread. Variable with null value is also valid. REFERENCE type.
- $allowThreadExitCodes : bool
-
Activates the support of thread exit codes. In that case the programmer needs to make sure that before the creation of a heavy thread there are no initialized objects whose destructors and particularly their multiple execution (in all the children and once in the parent) will affect the execution of the program in an undefined way.
__destruct()
Destructor (default). It will not be called in the heavy thread if thread exit codes are disabled!
public
__destruct() : mixed
BGN_HIGH_PRIOR_EXEC_BLOCK()
Marks the start of a code block with high execution priority.
public
final static BGN_HIGH_PRIOR_EXEC_BLOCK() : void
END_HIGH_PRIOR_EXEC_BLOCK()
Marks the end of a code block with high execution priority.
public
final static END_HIGH_PRIOR_EXEC_BLOCK() : void
getExitCode()
Returns the thread's exit code.
public
final getExitCode() : int
Return values
intgetPid()
Returns the current thread's (process) id.
public
getPid() : int|bool
Return values
int|bool —On success returns a number different than 0. Otherwise returns false.
getPriority()
Returns the current execution priority of the thread.
public
getPriority() : int|bool
Return values
int|bool —On success the priority number in the interval [-20; 20] where the lower value means higher priority. On failure returns false.
isAlive()
Checks if the thread is alive.
public
isAlive() : bool
Return values
bool —Returns true if the thread is alive otherwise returns false.
isInGPhpThread()
Execution protector. Recommended to be used everywhere where execution is not desired.
public
static isInGPhpThread(null|GPhpThreadNotCloneableContainer &$isInsideGPhpThread) : null|bool
For e.g. destructors which should be executed only in the master process. Indicates whether the place from which this method is called is a heavy thread or not.
Can be used in 2 different ways. A direct way where the supplied parameter points to NULL. In this case the result is immediately returned, but the user will not be able to ignore the effect in any "inner" threads without using resetThreadIdGenerator() method which on the other hand will affect any previously created object instances (before the thread was launched (forked)).
The other way is by subscribing a variable (most useful when is done in the constructor of your affected class). When subscribed initially its value will be set to false, but it will be updated after any calls to start()/stop().
Parameters
- $isInsideGPhpThread : null|GPhpThreadNotCloneableContainer
-
A REFERENCE type. If it's set to null, the function will immediately return the result. Otherwise the variable will be subscribed for the result during the program's execution and its initial value will be set to false.
Tags
Return values
null|bool —Null if a variable is subscribed for the result. Else if the method caller is part ot a heavy thread returns true otherwise false.
isParentAlive()
Checks if the creator of the heavy thread is alive.
public
isParentAlive() : bool
Return values
bool —Returns true if the parent is alive otherwise returns false.
join()
Waits for executing thread to return.
public
final join([bool $useBlocking = true ]) : bool
Parameters
- $useBlocking : bool = true
-
If is set to true will block the until the thread returns.
Return values
bool —True if the thread has joined otherwise false.
pause()
Pauses the execution of the thread.
public
final pause() : bool
Return values
bool —True if the pause request was successfully sent otherwise false.
resetThreadIdGenerator()
Resets the internal thread id generator. This can be used to allow creation of threads from another thread.
public
static resetThreadIdGenerator() : void
Not recommended to be used especially in a more complex cases.
resume()
Resumes the execution of a paused thread.
public
final resume() : bool
Return values
bool —True if the execution resume request was successfully sent otherwise false.
run()
Abstract method, the entry point of a particular GPhpThread inheritor implementation.
public
abstract run() : void
setPriority()
Sets the execution priority of the thread. A super user privileges are required.
public
setPriority(int $priority) : bool
Parameters
- $priority : int
-
The priority number in the interval [-20; 20] where the lower value means higher priority.
Return values
bool —Returns true on success otherwise returns false.
start()
Starts the thread.
public
final start() : bool
Return values
bool —On successful execution returns true otherwise returns false.
stop()
Stops executing thread.
public
final stop([bool $force = false ]) : bool
Parameters
- $force : bool = false
-
If it is set to true if performs forced stop (termination).
Return values
bool —True if the stop request was sent successfully otherwise false.
makeNicer()
At process level decreases the niceness of a heavy "thread" making its priority higher. Multiple calls of the method will accumulate and increase the effect.
protected
makeNicer() : bool
Tags
Return values
bool —Returns true on success or false in case of error or lack of privileges.
makeUnfriendlier()
At process level increases the niceness of a heavy "thread" making its priority lower. Multiple calls of the method will accumulate and increase the effect.
protected
makeUnfriendlier() : bool
Tags
Return values
bool —Returns true on success or false in case of error or lack of privileges.
milliSleep()
Suspends the thread execution for a specific amount of milliseconds, redirecting the CPU resources to somewhere else.
protected
milliSleep(int $milliseconds) : bool
Parameters
- $milliseconds : int
-
The delay in milliseconds.
Tags
Return values
bool —Returns true after all of the specified delay time elapsed. If the sleep was interrupted returns false.
setExitCode()
Specifies the running thread's exit code when it terminates.
protected
final setExitCode(int $exitCode) : void
Parameters
- $exitCode : int
-
The exit code with which the thread will quit.
sleep()
Suspends the thread execution for a specific amount of time, redirecting the CPU resources to somewhere else. The total delay is the sum of all passed parameters.
protected
sleep(int $microseconds[, int $seconds = 0 ]) : bool
Parameters
- $microseconds : int
-
The delay in microseconds.
- $seconds : int = 0
-
(optional) The delay in seconds.
Tags
Return values
bool —Returns true after all of the specified delay time elapsed. If the sleep was interrupted returns false.
amIParent()
Returns if the current process is a parent (has created thread).
private
amIParent() : bool
Return values
bool —If it is a parent returns true otherwise returns false.
notifyParentThatChildIsTerminated()
Notifies the parent of the current thread that the thread has exited.
private
notifyParentThatChildIsTerminated() : void