Page MenuHomePhabricator
Diviner Arcanist Tech Docs PhutilSocketChannel

final class PhutilSocketChannel
Arcanist Technical Documentation ()

Channel on an underlying stream socket or socket pair. For a description of channels, see PhutilChannel.

Using a network socket:

$socket = stream_socket_client(...);
$channel = new PhutilSocketChannel($socket);

Using stdin/stdout:

$channel = new PhutilSocketChannel(
  fopen('php://stdin', 'r'),
  fopen('php://stdout', 'w'));

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}.
  • public function isOpen()
  • public function closeWriteChannel()
  • public function isOpenForReading()
  • public function isOpenForWriting()
  • protected function readBytes($length)
  • protected function writeBytes($bytes)
  • protected function getReadSockets()
  • protected function getWriteSockets()
  • 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.

Construction

  • public function __construct($read_socket, $write_socket) — Construct a socket channel from a socket or a socket pair.
  • public static function newChannelPair() — Creates a pair of socket channels that are connected to each other. This is mostly useful for writing unit tests of, e.g., protocol channels.

Other Methods

Methods

public function __construct($read_socket, $write_socket)

Construct a socket channel from a socket or a socket pair.

NOTE: This must be a stream socket from stream_socket_client() or stream_socket_server() or similar, not a plain socket from socket_create() or similar.
Return
this//Implicit.//

public function read()
Inherited

PhutilChannel

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
wildData from the channel, normally bytes.

public function write($bytes)
Inherited

PhutilChannel

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$bytesData to write to the channel, normally bytes.
Return
this

public static function waitForAny($channels, $options)
Inherited

PhutilChannel

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

Parameters
list<PhutilChannel>$channelsA list of channels to wait for.
dict$optionsOptions, see above.
Return
void

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

PhutilChannel

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>$readsList of channels to wait for reads on.
list<PhutilChannel>$writesList of channels to wait for writes on.
array$options
Return
void

public function update()
Inherited

PhutilChannel

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

Return
boolTrue if the channel is still open.

public function setName($name)
Inherited

PhutilChannel

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

Parameters
string$nameChannel name.
Return
this

public function getName()
Inherited

PhutilChannel

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

Return
stringName of the channel.

public function isOpen()

PhutilChannel

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

PhutilSocketChannel
This method is not documented.
Return
boolTrue if the channel is open.

public function closeWriteChannel()

PhutilChannel

Close the channel for writing.

PhutilSocketChannel
This method is not documented.
Return
void

public function isOpenForReading()

PhutilChannel

Test if the channel is open for reading.

PhutilSocketChannel
This method is not documented.
Return
boolTrue if the channel is open for reading.

public function isOpenForWriting()

PhutilChannel

Test if the channel is open for writing.

PhutilSocketChannel
This method is not documented.
Return
boolTrue if the channel is open for writing.

protected function readBytes($length)

PhutilChannel

Read from the channel's underlying I/O.

PhutilSocketChannel
This method is not documented.
Parameters
int$lengthMaximum number of bytes to read.
Return
stringBytes, if available.

protected function writeBytes($bytes)

PhutilChannel

Write to the channel's underlying I/O.

PhutilSocketChannel
This method is not documented.
Parameters
string$bytesBytes to write.
Return
intNumber of bytes written.

protected function getReadSockets()

PhutilChannel

Get sockets to select for reading.

PhutilSocketChannel
This method is not documented.
Return
list<stream>Read sockets.

protected function getWriteSockets()

PhutilChannel

Get sockets to select for writing.

PhutilSocketChannel
This method is not documented.
Return
list<stream>Write sockets.

public function setReadBufferSize($size)
Inherited

PhutilChannel

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$sizeMaximum read buffer size, or `null` for a limitless buffer.
Return
this

public function isReadBufferEmpty()
Inherited

PhutilChannel

Test state of the read buffer.

Return
boolTrue if the read buffer is empty.

public function isWriteBufferEmpty()
Inherited

PhutilChannel

Test state of the write buffer.

Return
boolTrue if the write buffer is empty.

public function getWriteBufferSize()
Inherited

PhutilChannel

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

Return
intNumber of waiting bytes.

public function flush()
Inherited

PhutilChannel

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

Return
wild

public function __destruct()

This method is not documented.
Return
wild

public static function newChannelPair()

Creates a pair of socket channels that are connected to each other. This is mostly useful for writing unit tests of, e.g., protocol channels.

list($x, $y) = PhutilSocketChannel::newChannelPair();
Return
wild

private function closeReadSocket()

This method is not documented.
Return
wild

private function closeWriteSocket()

This method is not documented.
Return
wild

private function closeOneSocket($socket)

This method is not documented.
Parameters
$socket
Return
wild

private function closeSockets()

This method is not documented.
Return
wild
Defined
src/channel/PhutilSocketChannel.php:20
Extends
PhutilChannel
Phabricator · Built by Phacility