pthreads

Table of Contents

Introduction
Installing/Configuring
Predefined Constants
Threaded — The Threaded class
- Threaded::chunk — Manipulation
- Threaded::count — Manipulation
- Threaded::extend — Runtime Manipulation
- Threaded::from — Creation
- Threaded::getTerminationInfo — Error Detection
- Threaded::isRunning — State Detection
- Threaded::isTerminated — State Detection
- Threaded::isWaiting — State Detection
- Threaded::lock — Synchronization
- Threaded::merge — Manipulation
- Threaded::notify — Synchronization
- Threaded::pop — Manipulation
- Threaded::run — Execution
- Threaded::shift — Manipulation
- Threaded::synchronized — Synchronization
- Threaded::unlock — Synchronization
- Threaded::wait — Synchronization
Thread — The Thread class
- Thread::detach — Execution
- Thread::getCreatorId — Identification
- Thread::getCurrentThread — Identification
- Thread::getCurrentThreadId — Identification
- Thread::getThreadId — Identification
- Thread::globally — Execution
- Thread::isJoined — State Detection
- Thread::isStarted — State Detection
- Thread::join — Synchronization
- Thread::kill — Execution
- Thread::start — Execution
Worker — The Worker class
- Worker::collect — Collect references to completed tasks
- Worker::getStacked — Gets the remaining stack size
- Worker::isShutdown — State Detection
- Worker::isWorking — State Detection
- Worker::shutdown — Shutdown the worker
- Worker::stack — Stacking work
- Worker::unstack — Unstacking work
Collectable — The Collectable interface
- Collectable::isGarbage — Determine whether an object has been marked as garbage
- Collectable::setGarbage — Mark an object as garbage
Modifiers — Method Modifiers
Pool — The Pool class
- Pool::collect — Collect references to completed tasks
- Pool::__construct — Creates a new Pool of Workers
- Pool::resize — Resize the Pool
- Pool::shutdown — Shutdown all workers
- Pool::submit — Submits an object for execution
- Pool::submitTo — Submits a task to a specific worker for execution
Mutex — The Mutex class
- Mutex::create — Create a Mutex
- Mutex::destroy — Destroy Mutex
- Mutex::lock — Acquire Mutex
- Mutex::trylock — Attempt to Acquire Mutex
- Mutex::unlock — Release Mutex
Cond — The Cond class
- Cond::broadcast — Broadcast a Condition
- Cond::create — Create a Condition
- Cond::destroy — Destroy a Condition
- Cond::signal — Signal a Condition
- Cond::wait — Wait for Condition

The Threaded class

Introduction

Threaded objects form the basis of pthreads ability to execute user code in parallel; they expose synchronization methods and various useful interfaces.

Threaded objects, most importantly, provide implicit safety for the programmer; all operations on the object scope are safe.

Class synopsis

Threaded

class Threaded implements Traversable , Countable , ArrayAccess {

/* Methods */

public array chunk ( integer $size , boolean $preserve )

public integer count ( void )

public bool extend ( string $class )

public Threaded from ( Closure $run [, Closure $construct [, array $args ]] )

public array getTerminationInfo ( void )

public boolean isRunning ( void )

public boolean isTerminated ( void )

public boolean isWaiting ( void )

public boolean lock ( void )

public boolean merge ( mixed $from [, bool $overwrite ] )

public boolean notify ( void )

public boolean pop ( void )

public void run ( void )

public mixed shift ( void )

public mixed synchronized ( Closure $block [, mixed $... ] )

public boolean unlock ( void )

public boolean wait ([ integer $timeout ] )

}

The Thread class

Introduction

When the start method of a Thread is invoked, the run method code will be executed in separate Thread, in parallel.

After the run method is executed the Thread will exit immediately, it will be joined with the creating Thread at the appropriate time.

Warning

Relying on the engine to determine when a Thread should join may cause undesirable behaviour; the programmer should be explicit, where possible.

Class synopsis

Thread

class Thread extends Threaded implements Countable , Traversable , ArrayAccess {

/* Methods */

public void detach ( void )

public integer getCreatorId ( void )

public static Thread getCurrentThread ( void )

public static integer getCurrentThreadId ( void )

public integer getThreadId ( void )

public static mixed globally ( void )

public boolean isJoined ( void )

public boolean isStarted ( void )

public boolean join ( void )

public void kill ( void )

public boolean start ([ integer $options ] )

/* Inherited methods */

public array Threaded::chunk ( integer $size , boolean $preserve )

public integer Threaded::count ( void )

public bool Threaded::extend ( string $class )

public Threaded Threaded::from ( Closure $run [, Closure $construct [, array $args ]] )

public array Threaded::getTerminationInfo ( void )

public boolean Threaded::isRunning ( void )

public boolean Threaded::isTerminated ( void )

public boolean Threaded::isWaiting ( void )

public boolean Threaded::lock ( void )

public boolean Threaded::merge ( mixed $from [, bool $overwrite ] )

public boolean Threaded::notify ( void )

public boolean Threaded::pop ( void )

public void Threaded::run ( void )

public mixed Threaded::shift ( void )

public mixed Threaded::synchronized ( Closure $block [, mixed $... ] )

public boolean Threaded::unlock ( void )

public boolean Threaded::wait ([ integer $timeout ] )

}

The Worker class

Introduction

Worker Threads have a persistent context, as such should be used over Threads in most cases.

When a Worker is started, the run method will be executed, but the Thread will not leave until one of the following conditions are met:

the Worker goes out of scope (no more references remain)
the programmer calls shutdown
the script dies

This means the programmer can reuse the context throughout execution; placing objects on the stack of the Worker will cause the Worker to execute the stacked objects run method.

Warning

The programmer must retain references to stacked objects until they are executed or unstacked; the Pool class provides a higher level abstraction of the Worker functionality and manages references for the programmer.

Class synopsis

Worker

class Worker extends Thread implements Traversable , Countable , ArrayAccess {

/* Methods */

public int collect ([ Callable $collector ] )

public int getStacked ( void )

public bool isShutdown ( void )

public boolean isWorking ( void )

public bool shutdown ( void )

public int stack ( Threaded &$work )

public int unstack ( void )

/* Inherited methods */

public void Thread::detach ( void )

public integer Thread::getCreatorId ( void )

public static Thread Thread::getCurrentThread ( void )

public static integer Thread::getCurrentThreadId ( void )

public integer Thread::getThreadId ( void )

public static mixed Thread::globally ( void )

public boolean Thread::isJoined ( void )

public boolean Thread::isStarted ( void )

public boolean Thread::join ( void )

public void Thread::kill ( void )

public boolean Thread::start ([ integer $options ] )

}

The Collectable interface

Introduction

Caution

Collectable was previously a class (in pthreads v2 and below). Now, it is an interface in pthreads v3 that is implemented by the Threaded class.

Represents a garbage-collectable object.

Interface synopsis

Collectable

class Collectable extends Threaded {

/* Methods */

public bool isGarbage ( void )

public void setGarbage ( void )

}

The Pool class

Introduction

A Pool is a container for, and controller of, an adjustable number of Workers.

Pooling provides a higher level abstraction of the Worker functionality, including the management of references in the way required by pthreads.

Class synopsis

Pool

class Pool {

/* Properties */

protected $size ;

protected $class ;

protected $workers ;

protected $work ;

protected $ctor ;

protected $last ;

/* Methods */

public int collect ([ Callable $collector ] )

public Pool __construct ( integer $size [, string $class [, array $ctor ]] )

public void resize ( integer $size )

public void shutdown ( void )

public int submit ( Threaded $task )

public int submitTo ( int $worker , Threaded $task )

}

Properties

size: maximum number of Workers this Pool can use
class: the class of the Worker
ctor: the arguments for constructor of new Workers
workers: references to Workers
work: references to Threaded objects submitted to the Pool
last: offset in workers of the last Worker used

The Mutex class

Introduction

Warning

The Mutex class has been removed in pthreads v3.

The static methods contained in the Mutex class provide direct access to Posix Mutex functionality.

Class synopsis

Mutex

class Mutex {

/* Methods */

final public static long create ([ boolean $lock ] )

final public static boolean destroy ( long $mutex )

final public static boolean lock ( long $mutex )

final public static boolean trylock ( long $mutex )

final public static boolean unlock ( long $mutex [, boolean $destroy ] )

}

The Cond class

Introduction

Warning

The Cond class has been removed in pthreads v3.

The static methods contained in the Cond class provide direct access to Posix Condition Variables.

Class synopsis

Cond

class Cond {

/* Methods */

final public static boolean broadcast ( long $condition )

final public static long create ( void )

final public static boolean destroy ( long $condition )

final public static boolean signal ( long $condition )

final public static boolean wait ( long $condition , long $mutex [, long $timeout ] )

}