Book/sync-Phpdoc专题

Sync

简介
安装／配置
预定义常量
SyncMutex — The SyncMutex class
- SyncMutex::__construct — Constructs a new SyncMutex object
- SyncMutex::lock — Waits for an exclusive lock
- SyncMutex::unlock — Unlocks the mutex
SyncSemaphore — The SyncSemaphore class
- SyncSemaphore::__construct — Constructs a new SyncSemaphore object
- SyncSemaphore::lock — Decreases the count of the semaphore or waits
- SyncSemaphore::unlock — Increases the count of the semaphore
SyncEvent — The SyncEvent class
- SyncEvent::__construct — Constructs a new SyncEvent object
- SyncEvent::fire — Fires/sets the event
- SyncEvent::reset — Resets a manual event
- SyncEvent::wait — Waits for the event to be fired/set
SyncReaderWriter — The SyncReaderWriter class
- SyncReaderWriter::__construct — Constructs a new SyncReaderWriter object
- SyncReaderWriter::readlock — Waits for a read lock
- SyncReaderWriter::readunlock — Releases a read lock
- SyncReaderWriter::writelock — Waits for an exclusive write lock
- SyncReaderWriter::writeunlock — Releases a write lock
SyncSharedMemory — The SyncSharedMemory class
- SyncSharedMemory::__construct — Constructs a new SyncSharedMemory object
- SyncSharedMemory::first — Check to see if the object is the first instance system-wide of named shared memory
- SyncSharedMemory::read — Copy data from named shared memory
- SyncSharedMemory::size — Returns the size of the named shared memory
- SyncSharedMemory::write — Copy data to named shared memory

简介

A cross-platform, native implementation of named and unnamed countable mutex objects.

A mutex is a mutual exclusion object that restricts access to a shared resource (e.g. a file) to a single instance. Countable mutexes acquire the mutex a single time and internally track the number of times the mutex is locked. The mutex is unlocked as soon as it goes out of scope or is unlocked the same number of times that it was locked.

类摘要

SyncMutex

class SyncMutex {

/* 方法 */

public __construct ([ string $name ] )

public bool lock ([ int $wait = -1 ] )

public bool unlock ([ bool $all = false ] )

}

SyncMutex::__construct

Constructs a new SyncMutex object

说明

public SyncMutex::__construct ([ string $name ] )

Constructs a named or unnamed countable mutex.

参数

name
The name of the mutex if this is a named mutex object.

Note:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

返回值

The new SyncMutex object. An exception is thrown if the mutex cannot be created or opened.

范例

示例 #1 SyncMutex::__construct named mutex with lock timeout example

<?php
$mutex = new SyncMutex("UniqueName");

if (!$mutex->lock(3000))
{
    echo "Unable to lock mutex.";

    exit();
}

/* ... */

$mutex->unlock();
?>

示例 #2 SyncMutex::__construct unnamed mutex example

<?php
$mutex = new SyncMutex();

$mutex->lock();

/* ... */

$mutex->unlock();
?>

参见

SyncMutex::lock
SyncMutex::unlock

SyncMutex::lock

Waits for an exclusive lock

说明

public bool SyncMutex::lock ([ int $wait = -1 ] )

Obtains an exclusive lock on a SyncMutex object. If the lock is already acquired, then this increments an internal counter.

参数

wait
The number of milliseconds to wait for the exclusive lock. A value of -1 is infinite.

返回值

A boolean of TRUE if the lock was obtained, FALSE otherwise.

范例

示例 #1 SyncMutex::lock example

<?php
$mutex = new SyncMutex("UniqueName");

if (!$mutex->lock(3000))
{
    echo "Unable to lock mutex.";

    exit();
}

/* ... */

$mutex->unlock();
?>

参见

SyncMutex::unlock

SyncMutex::unlock

Unlocks the mutex

说明

public bool SyncMutex::unlock ([ bool $all = false ] )

Decreases the internal counter of a SyncMutex object. When the internal counter reaches zero, the actual lock on the object is released.

参数

all
Specifies whether or not to set the internal counter to zero and therefore release the lock.

返回值

A boolean of TRUE if the unlock operation was successful, FALSE otherwise.

范例

示例 #1 SyncMutex::unlock example

<?php
$mutex = new SyncMutex("UniqueName");

$mutex->lock();

/* ... */

$mutex->unlock();
?>

参见

SyncMutex::lock

简介

A cross-platform, native implementation of named and unnamed semaphore objects.

A semaphore restricts access to a limited resource to a limited number of instances. Semaphores differ from mutexes in that they can allow more than one instance to access a resource at one time while a mutex only allows one instance at a time.

类摘要

SyncSemaphore

class SyncSemaphore {

/* 方法 */

public __construct ([ string $name [, int $initialval = 1 [, bool $autounlock = true ]]] )

public bool lock ([ int $wait = -1 ] )

public bool unlock ([ int &$prevcount ] )

}

SyncSemaphore::__construct

Constructs a new SyncSemaphore object

说明

public SyncSemaphore::__construct ([ string $name [, int $initialval = 1 [, bool $autounlock = true ]]] )

Constructs a named or unnamed semaphore.

参数

name
The name of the semaphore if this is a named semaphore object.

Note:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

initialval
The initial value of the semaphore. This is the number of locks that may be obtained.

autounlock
Specifies whether or not to automatically unlock the semaphore at the conclusion of the PHP script.

Warning If an object is: A named semaphore with an autounlock of FALSE, the object is locked, and the PHP script concludes before the object is unlocked, then the underlying semaphore will end up in an inconsistent state.

返回值

The new SyncSemaphore object. An exception is thrown if the semaphore cannot be created or opened.

范例

示例 #1 SyncSemaphore::__construct example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
    echo "Unable to lock semaphore.";

    exit();
}

/* ... */

$semaphore->unlock();
?>

参见

SyncSemaphore::lock
SyncSemaphore::unlock

SyncSemaphore::lock

Decreases the count of the semaphore or waits

说明

public bool SyncSemaphore::lock ([ int $wait = -1 ] )

Decreases the count of a SyncSemaphore object or waits until the semaphore becomes non-zero.

参数

wait
The number of milliseconds to wait for the semaphore. A value of -1 is infinite.

返回值

A boolean of TRUE if the lock operation was successful, FALSE otherwise.

范例

示例 #1 SyncSemaphore::lock example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
    echo "Unable to lock semaphore.";

    exit();
}

/* ... */

$semaphore->unlock();
?>

参见

SyncSemaphore::unlock

SyncSemaphore::unlock

Increases the count of the semaphore

说明

public bool SyncSemaphore::unlock ([ int &$prevcount ] )

Increases the count of a SyncSemaphore object.

参数

prevcount
Returns the previous count of the semaphore.

返回值

A boolean of TRUE if the unlock operation was successful, FALSE otherwise.

范例

示例 #1 SyncSemaphore::unlock example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
    echo "Unable to lock semaphore.";

    exit();
}

/* ... */

$semaphore->unlock();
?>

参见

SyncSemaphore::lock

简介

A cross-platform, native implementation of named and unnamed event objects. Both automatic and manual event objects are supported.

An event object waits, without polling, for the object to be fired/set. One instance waits on the event object while another instance fires/sets the event. Event objects are useful wherever a long-running process would otherwise poll a resource (e.g. checking to see if uploaded data needs to be processed).

类摘要

SyncEvent

class SyncEvent {

/* 方法 */

public __construct ([ string $name [, bool $manual = false [, bool $prefire = false ]]] )

public bool fire ( void )

public bool reset ( void )

public bool wait ([ int $wait = -1 ] )

}

SyncEvent::__construct

Constructs a new SyncEvent object

说明

public SyncEvent::__construct ([ string $name [, bool $manual = false [, bool $prefire = false ]]] )

Constructs a named or unnamed event object.

参数

name
The name of the event if this is a named event object.

Note:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

manual
Specifies whether or not the event object must be reset manually.

Note:

Manual reset event objects allow all waiting processes through until the object is reset.

prefire
Specifies whether or not to prefire (signal) the event object.

Note:

Only has impact if the calling process/thread is the first to create the object.

返回值

The new SyncEvent object. An exception is thrown if the event object cannot be created or opened.

范例

示例 #1 SyncEvent::__construct example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

更新日志

版本	说明
PECL sync 1.1.0	Added `prefire`.

参见

SyncEvent::fire
SyncEvent::reset
SyncEvent::wait

SyncEvent::fire

Fires/sets the event

说明

public bool SyncEvent::fire ( void )

Fires/sets a SyncEvent object. Lets multiple threads through that are waiting if the event object was created with a manual value of TRUE.

参数

此函数没有参数。

返回值

A boolean of TRUE if the event was fired, FALSE otherwise.

范例

示例 #1 SyncEvent::fire example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

参见

SyncEvent::reset
SyncEvent::wait

SyncEvent::reset

Resets a manual event

说明

public bool SyncEvent::reset ( void )

Resets a SyncEvent object that has been fired/set. Only valid for manual event objects.

参数

此函数没有参数。

返回值

A boolean value of TRUE if the object was successfully reset, FALSE otherwise.

范例

示例 #1 SyncEvent::reset example

<?php
// In a web application:
$event = new SyncEvent("DemoApplication", true);
$event->wait();

// In a cron job:
$event = new SyncEvent("DemoApplication", true);
$event->reset();
/* ... Do some maintenance task(s) ... */
$event->fire();
?>

参见

SyncEvent::fire
SyncEvent::reset
SyncEvent::wait

SyncEvent::wait

Waits for the event to be fired/set

说明

public bool SyncEvent::wait ([ int $wait = -1 ] )

Waits for the SyncEvent object to be fired.

参数

wait
The number of milliseconds to wait for the event to be fired. A value of -1 is infinite.

返回值

A boolean of TRUE if the event was fired, FALSE otherwise.

范例

示例 #1 SyncEvent::wait example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

参见

SyncEvent::fire

简介

A cross-platform, native implementation of named and unnamed reader-writer objects.

A reader-writer object allows many readers or one writer to access a resource. This is an efficient solution for managing resources where access will primarily be read-only but exclusive write access is occasionally necessary.

类摘要

SyncReaderWriter

class SyncReaderWriter {

/* 方法 */

public __construct ([ string $name [, bool $autounlock = true ]] )

public bool readlock ([ int $wait = -1 ] )

public bool readunlock ( void )

public bool writelock ([ int $wait = -1 ] )

public bool writeunlock ( void )

}

SyncReaderWriter::__construct

Constructs a new SyncReaderWriter object

说明

public SyncReaderWriter::__construct ([ string $name [, bool $autounlock = true ]] )

Constructs a named or unnamed reader-writer object.

参数

name
The name of the reader-writer if this is a named reader-writer object.

Note:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

autounlock
Specifies whether or not to automatically unlock the reader-writer at the conclusion of the PHP script.

Warning If an object is: A named reader-writer with an autounlock of FALSE, the object is locked for either reading or writing, and the PHP script concludes before the object is unlocked, then the underlying objects will end up in an inconsistent state.

返回值

The new SyncReaderWriter object. An exception is thrown if the reader-writer cannot be created or opened.

范例

示例 #1 SyncReaderWriter::__construct example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();

$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参见

SyncReaderWriter::readlock
SyncReaderWriter::readunlock
SyncReaderWriter::writelock
SyncReaderWriter::writeunlock

SyncReaderWriter::readlock

Waits for a read lock

说明

public bool SyncReaderWriter::readlock ([ int $wait = -1 ] )

Obtains a read lock on a SyncReaderWriter object.

参数

wait
The number of milliseconds to wait for a lock. A value of -1 is infinite.

返回值

A boolean of TRUE if the lock was obtained, FALSE otherwise.

范例

示例 #1 SyncReaderWriter::readlock example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();
?>

参见

SyncReaderWriter::readunlock

SyncReaderWriter::readunlock

Releases a read lock

说明

public bool SyncReaderWriter::readunlock ( void )

Releases a read lock on a SyncReaderWriter object.

参数

此函数没有参数。

返回值

A boolean of TRUE if the unlock operation was successful, FALSE otherwise.

范例

示例 #1 SyncReaderWriter::readunlock example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();
?>

参见

SyncReaderWriter::readlock

SyncReaderWriter::writelock

Waits for an exclusive write lock

说明

public bool SyncReaderWriter::writelock ([ int $wait = -1 ] )

Obtains an exclusive write lock on a SyncReaderWriter object.

参数

wait
The number of milliseconds to wait for a lock. A value of -1 is infinite.

返回值

A boolean of TRUE if the lock was obtained, FALSE otherwise.

范例

示例 #1 SyncReaderWriter::writelock example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参见

SyncReaderWriter::writeunlock

SyncReaderWriter::writeunlock

Releases a write lock

说明

public bool SyncReaderWriter::writeunlock ( void )

Releases a write lock on a SyncReaderWriter object.

参数

此函数没有参数。

返回值

A boolean of TRUE if the unlock operation was successful, FALSE otherwise.

范例

示例 #1 SyncReaderWriter::writeunlock example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参见

SyncReaderWriter::writelock

简介

A cross-platform, native, consistent implementation of named shared memory objects.

Shared memory lets two separate processes communicate without the need for complex pipes or sockets. There are several integer-based shared memory implementations for PHP. Named shared memory is an alternative.

Synchronization objects (e.g. SyncMutex) are still required to protect most uses of shared memory.

类摘要

SyncSharedMemory

class SyncSharedMemory {

/* 方法 */

public __construct ( string $name , int $size )

public bool first ( void )

public read ([ int $start = 0 [, int $length ]] )

public bool size ( void )

public write ([ string $string [, int $start = 0 ]] )

}

SyncSharedMemory::__construct

Constructs a new SyncSharedMemory object

说明

public SyncSharedMemory::__construct ( string $name , int $size )

Constructs a named shared memory object.

参数

name
The name of the shared memory object.

Note:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

size
The size, in bytes, of shared memory to reserve.

Note:

The amount of memory cannot be resized later. Request sufficient storage up front.

返回值

The new SyncSharedMemory object. An exception is thrown if the shared memory object cannot be created or opened.

范例

示例 #1 SyncSharedMemory::__construct example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
    // Do first time initialization work here.
}

$result = $mem->write(json_encode(array("name" => "my_report.txt")));
?>

参见

SyncSharedMemory::first
SyncSharedMemory::size
SyncSharedMemory::write
SyncSharedMemory::read

SyncSharedMemory::first

Check to see if the object is the first instance system-wide of named shared memory

说明

public bool SyncSharedMemory::first ( void )

Retrieves the system-wide first instance status of a SyncSharedMemory object.

参数

此函数没有参数。

返回值

A boolean of TRUE if the object is the first instance system-wide, FALSE otherwise.

范例

示例 #1 SyncSharedMemory::first example

<?php
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
    // Do first time initialization work here.
}

var_dump($mem->first());

$mem2 = new SyncSharedMemory("AppReportName", 1024);

var_dump($mem2->first());
?>

以上例程的输出类似于：

bool(true)
bool(false)

参见

SyncSharedMemory::write
SyncSharedMemory::read

SyncSharedMemory::read

Copy data from named shared memory

说明

public SyncSharedMemory::read ([ int $start = 0 [, int $length ]] )

Copies data from named shared memory.

参数

start
The start/offset, in bytes, to begin reading.

Note:

If the value is negative, the starting position will begin at the specified number of bytes from the end of the shared memory segment.

length
The number of bytes to read.

Note:

If unspecified, reading will stop at the end of the shared memory segment.

If the value is negative, reading will stop the specified number of bytes from the end of the shared memory segment.

返回值

A string containing the data read from shared memory.

范例

示例 #1 SyncSharedMemory::__construct example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
    // Do first time initialization work here.
}

$result = $mem->write("report.txt");

$result = $mem->read(3, -4);
var_dump($result);
?>

以上例程的输出类似于：

string(3) "ort"

参见

SyncSharedMemory::__construct
SyncSharedMemory::first
SyncSharedMemory::write
SyncSharedMemory::read

SyncSharedMemory::size

Returns the size of the named shared memory

说明

public bool SyncSharedMemory::size ( void )

Retrieves the shared memory size of a SyncSharedMemory object.

参数

此函数没有参数。

返回值

An integer containing the size of the shared memory. This will be the same size that was passed to the constructor.

范例

示例 #1 SyncSharedMemory::size example

<?php
$mem = new SyncSharedMemory("AppReportName", 1024);
var_dump($mem->size());
?>

以上例程的输出类似于：

int(1024)

参见

SyncSharedMemory::__construct
SyncSharedMemory::write
SyncSharedMemory::read

SyncSharedMemory::write

Copy data to named shared memory

说明

public SyncSharedMemory::write ([ string $string [, int $start = 0 ]] )

Copies data to named shared memory.

参数

string
The data to write to shared memoy.

Note:

If the size of the data exceeds the size of the shared memory, the number of bytes written returned will be less than the length of the input.

start
The start/offset, in bytes, to begin writing.

Note:

If the value is negative, the starting position will begin at the specified number of bytes from the end of the shared memory segment.

返回值

An integer containing the number of bytes written to shared memory.

范例

示例 #1 SyncSharedMemory::write example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
    // Do first time initialization work here.
}

$result = $mem->write("report.txt");
var_dump($result);

$result = $mem->write("report.txt", -3);
var_dump($result);
?>

以上例程的输出类似于：

int(10)
int(3)

参见

SyncSharedMemory::__construct
SyncSharedMemory::first
SyncSharedMemory::write
SyncSharedMemory::read