Diviner Arcanist Tech Docs PhutilChannel

abstract class PhutilChannel
Arcanist Technical Documentation ()

Wrapper around streams, pipes, and other things that have basic read/write I/O characteristics.

Channels include buffering, so you can do fire-and-forget writes and reads without worrying about network/pipe buffers. Use read() and write() to read and write.

Channels are nonblocking and provide a select()-oriented interface so you can reasonably write server-like and daemon-like things with them. Use waitForAny() to select channels.

Channel operations other than update() generally operate on buffers. Writes and reads affect buffers, while update() flushes output buffers and fills input buffers.

Channels are either "open" or "closed". You can detect that a channel has closed by calling isOpen() or examining the return value of update().

NOTE: Channels are new (as of June 2012) and subject to interface changes.

Tasks

Reading and Writing

public function read() — Read from the channel. A channel defines the format of data that is read from it, so this method may return strings, objects, or anything else.
public function write($bytes) — Write to the channel. A channel defines what data format it accepts, so this method may take strings, objects, or anything else.

Waiting for Activity

public static function waitForAny($channels, $options) — Wait for any activity on a list of channels. Convenience wrapper around @{method:waitForActivity}.
public static function waitForActivity($reads, $writes, $options) — Wait (using select()) for channels to become ready for reads or writes. This method blocks until some channel is ready to be updated.

Responding to Activity

public function update() — Updates the channel, filling input buffers and flushing output buffers. Returns false if the channel has closed.

Channel Implementation

public function setName($name) — Set a channel name. This is primarily intended to allow you to debug channel code more easily, by naming channels something meaningful.
public function getName() — Get the channel name, as set by @{method:setName}.
abstract public function isOpen() — Test if the channel is open: active, can be read from and written to, etc.
abstract public function closeWriteChannel() — Close the channel for writing.
public function isOpenForReading() — Test if the channel is open for reading.
public function isOpenForWriting() — Test if the channel is open for writing.
abstract protected function readBytes($length) — Read from the channel's underlying I/O.
abstract protected function writeBytes($bytes) — Write to the channel's underlying I/O.
protected function getReadSockets() — Get sockets to select for reading.
protected function getWriteSockets() — Get sockets to select for writing.
public function setReadBufferSize($size) — Set the maximum size of the channel's read buffer. Reads will artificially block once the buffer reaches this size until the in-process buffer is consumed.
public function isReadBufferEmpty() — Test state of the read buffer.
public function isWriteBufferEmpty() — Test state of the write buffer.
public function getWriteBufferSize() — Get the number of bytes we're currently waiting to write.
public function flush() — Wait for any buffered writes to complete. This is a blocking call. When the call returns, the write buffer will be empty.

Other Methods

public function __get($name)
public function __set($name, $value)
public function current()
public function key()
public function next()
public function rewind()
public function valid()
private function throwOnAttemptedIteration()
public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
public function __construct()

Methods

public function __get($name)
Inherited

This method is not documented.

Parameters

$name

Return

wild

public function __set($name, $value)
Inherited

This method is not documented.

Parameters

	$name
	$value

Return

wild

public function current()
Inherited

This method is not documented.

Return

wild

public function key()
Inherited

This method is not documented.

Return

wild

public function next()
Inherited

This method is not documented.

Return

wild

public function rewind()
Inherited

This method is not documented.

Return

wild

public function valid()
Inherited

This method is not documented.

Return

wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.

Return

wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters

string	$key	Name of the constant.
int\|null	$byte_limit	Maximum number of bytes permitted in the value.

Return

string

Value of the constant.

public function __construct()

This method is not documented.

Return

this	//Implicit.//

public function read()

Read from the channel. A channel defines the format of data that is read from it, so this method may return strings, objects, or anything else.

The default implementation returns bytes.

Return

wild	Data from the channel, normally bytes.

public function write($bytes)

Write to the channel. A channel defines what data format it accepts, so this method may take strings, objects, or anything else.

The default implementation accepts bytes.

Parameters

wild

$bytes

Data to write to the channel, normally bytes.

Return

this

public static function waitForAny($channels, $options)

Wait for any activity on a list of channels. Convenience wrapper around waitForActivity().

Parameters

list<PhutilChannel>	$channels	A list of channels to wait for.
dict	$options	Options, see above.

Return

void

public static function waitForActivity($reads, $writes, $options)

Wait (using select()) for channels to become ready for reads or writes. This method blocks until some channel is ready to be updated.

It does not provide a way to determine which channels are ready to be updated. The expectation is that you'll just update every channel. This might change eventually.

Available options are:

'read' (list<stream>) Additional streams to select for read.
'write' (list<stream>) Additional streams to select for write.
'except' (list<stream>) Additional streams to select for except.
'timeout' (float) Select timeout, defaults to 1.

NOTE: Extra streams must be streams, not sockets, because this method uses stream_select(), not socket_select().

Parameters

list<PhutilChannel>	$reads	List of channels to wait for reads on.
list<PhutilChannel>	$writes	List of channels to wait for writes on.
array	$options

Return

void

public function update()

Updates the channel, filling input buffers and flushing output buffers. Returns false if the channel has closed.

Return

bool	True if the channel is still open.

public function setName($name)

Set a channel name. This is primarily intended to allow you to debug channel code more easily, by naming channels something meaningful.

Parameters

string

$name

Channel name.

Return

this

public function getName()

Get the channel name, as set by setName().

Return

string

Name of the channel.

abstract public function isOpen()

Test if the channel is open: active, can be read from and written to, etc.

Return

bool	True if the channel is open.

abstract public function closeWriteChannel()

Close the channel for writing.

Return

void

public function isOpenForReading()

Test if the channel is open for reading.

Return

bool	True if the channel is open for reading.

public function isOpenForWriting()

Test if the channel is open for writing.

Return

bool	True if the channel is open for writing.

abstract protected function readBytes($length)

Read from the channel's underlying I/O.

Parameters

int

$length

Maximum number of bytes to read.

Return

string

Bytes, if available.

abstract protected function writeBytes($bytes)

Write to the channel's underlying I/O.

Parameters

string

$bytes

Bytes to write.

Return

int	Number of bytes written.

protected function getReadSockets()

Get sockets to select for reading.

Return

list<stream>

Read sockets.

protected function getWriteSockets()

Get sockets to select for writing.

Return

list<stream>

Write sockets.

public function setReadBufferSize($size)

Set the maximum size of the channel's read buffer. Reads will artificially block once the buffer reaches this size until the in-process buffer is consumed.

Parameters

int|null

$size

Maximum read buffer size, or `null` for a limitless buffer.

Return

this

public function isReadBufferEmpty()

Test state of the read buffer.

Return

bool	True if the read buffer is empty.

public function isWriteBufferEmpty()

Test state of the write buffer.

Return

bool	True if the write buffer is empty.

public function getWriteBufferSize()

Get the number of bytes we're currently waiting to write.

Return

int	Number of waiting bytes.

public function flush()

Wait for any buffered writes to complete. This is a blocking call. When the call returns, the write buffer will be empty.

Return

wild

Defined: src/channel/PhutilChannel.php:30
Extends: Phobject

abstract class PhutilChannelArcanist Technical Documentation ()

Tasks

Reading and Writing

Waiting for Activity

Responding to Activity

Channel Implementation

Other Methods

Methods

public function __get($name)Inherited

public function __set($name, $value)Inherited

public function current()Inherited

public function key()Inherited

public function next()Inherited

public function rewind()Inherited

public function valid()Inherited

private function throwOnAttemptedIteration()Inherited

public function getPhobjectClassConstant($key, $byte_limit)Inherited

public function __construct()

public function read()

public function write($bytes)

public static function waitForAny($channels, $options)

public static function waitForActivity($reads, $writes, $options)

public function update()

public function setName($name)

public function getName()

abstract public function isOpen()

abstract public function closeWriteChannel()

public function isOpenForReading()

public function isOpenForWriting()

abstract protected function readBytes($length)

abstract protected function writeBytes($bytes)

protected function getReadSockets()

protected function getWriteSockets()

public function setReadBufferSize($size)

public function isReadBufferEmpty()

public function isWriteBufferEmpty()

public function getWriteBufferSize()

public function flush()

abstract class PhutilChannel
Arcanist Technical Documentation ()

public function __get($name)
Inherited

public function __set($name, $value)
Inherited

public function current()
Inherited

public function key()
Inherited

public function next()
Inherited

public function rewind()
Inherited

public function valid()
Inherited

private function throwOnAttemptedIteration()
Inherited

public function getPhobjectClassConstant($key, $byte_limit)
Inherited