Stream Component

• Introduction
• Features
• Concepts
• Examples
  • Creating Asynchronous Streams
  • Creating Streams
  • Reading With Streams
  • Writing With Streams
• Important Classes & Interfaces
  • AsyncStream
  • AsyncStreamInterface
  • AsyncStreamReader
  • AsyncStreamReaderInterface
  • AsyncStreamWriter
  • AsyncStreamWriterInterface
  • Stream
  • StreamInterface
  • StreamReader
  • StreamReaderInterface
  • StreamWriter
  • StreamWriterInterface
  • StreamSeeker
  • StreamSeekerInterface

Introduction

Stream is a component that provides consistent interface for managing and operating on stream including asynchronous writing and reading.

Features

Stream features:

Concepts

This section contains terminology, useful concepts and definitions, that might be helpful to learn to fully understand this component purpose.

Asynchronous Processing

Asynchronous processing is an approach of processing instructions in non-blocking way, that only initiates the operations without wait for response. The response is discovered later using specially designed mechanisms. You can learn more in asynchronity section.

Examples

This section contains examples and patterns that can be used with described component.

Creating Async Streams

All of asynchronous streams' constructors are also the same. This applies to AsyncStream, AsyncStreamReader and AsyncStreamWriter.

$stream = new AsyncStream($resource, $loop); // $loop have to be instance of Kraken\Loop\LoopInterface

Creating Streams

All of synchronous streams' constructors are the same. This applies to Stream, StreamReader, StreamWriter and StreamSeeker.

$stream = new Stream($resource);

Reading With Streams

Regardless of chosen type of stream, might it be a synchronous or asynchronous one, the API is the same. The only difference is that in synchronous stream readers the read operation is blocking and returns read value while in asynchronous it is non-blocking, and the only way of obtaining read value is via event data.

$reader->on('data', function($reader, $data) {
    // data event will be fired regardless of sync or async reading method
});
$reader->on('close', function() {
    // close event will also be fired
});

$data = $reader->read(); // this operation is blocking or non-blocking depending on stream type
$reader->close();

Writing With Streams

Regardless of chosen type of stream, might it be a synchronous or asynchronous one, the API is the same. The only difference is that in synchronous stream writers the write operation is blocking, while in asynchronous it is non-blocking.

$writer->on('drain', function() {
    // drain event will be fired regardless of sync or async writing method
});
$writer->on('close', function() {
    // close event will also be fired
});

$writer->write($data); // this operation is blocking or non-blocking depending on stream type
$writer->close();

Important Classes & Interfaces

This section contains list of most important classes and interfaces shipped with this component. It does not include all classes and interface.

AsyncStream

class AsyncStream extends Stream implements AsyncStreamInterface

AsyncStream is a concrete implementation of stream API allowing asynchronous reading and writing.

AsyncStreamInterface

interface AsyncStreamInterface extends AsyncStreamWriterInterface, AsyncStreamReaderInterface

AsyncStreamReader

class AsyncStreamReader extends StreamReader implements AsyncStreamReaderInterface

AsyncStreamReader is a concrete implementation of stream API allowing asynchronous reading.

AsyncStreamReaderInterface

interface AsyncStreamReaderInterface extends StreamReaderInterface, LoopResourceInterface

AsyncStreamWriter

class AsyncStreamWriter extends StreamWriter implements AsyncStreamWriterInterface

AsyncStreamWriter is a concrete implementation of stream API allowing asynchronous writing.

AsyncStreamWriterInterface

interface AsyncStreamWriterInterface extends StreamWriterInterface, LoopResourceInterface

Stream

class Stream extends StreamSeeker implements StreamInterface

Stream is a concrete implementation of stream API allowing reading and writing synchronously.

StreamInterface

interface StreamInterface extends StreamWriterInterface, StreamReaderInterface

StreamReader

class StreamReader extends StreamSeeker implements StreamReaderInterface

StreamReader is a concrete implementation of stream API allowing reading synchronously.

StreamReaderInterface

/**
 * @event data : callable(object, string)
 */
interface StreamReaderInterface extends EventEmitterInterface, StreamSeekerInterface

StreamWriter

class StreamWriter extends StreamSeeker implements StreamWriterInterface

StreamWriter is a concrete implementation of stream API allowing writing synchronously.

StreamWriterInterface

/**
 * @event drain : callable(object)
 */
interface StreamWriterInterface extends EventEmitterInterface, StreamSeekerInterface

StreamSeeker

class StreamSeeker extends BaseEventEmitter implements StreamSeekerInterface

StreamSeeker is a concrete implementation of stream API without possibility of reading or writing.

StreamSeekerInterface

/**
 * @event seek : callable(object, int)
 */
interface StreamSeekerInterface extends EventEmitterInterface, StreamBaseInterface