8000 Improve usage documentation by clue · Pull Request #102 · reactphp/stream · GitHub
[go: up one dir, main page]
Skip to content

Improve usage documentation #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 4, 2017
Merged

Improve usage documentation #102

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
60d453d
Add dedicated chapters for using and creating streams
clue May 3, 2017
b805d3f
Add warning about closed STDIN PHP bug
clue May 3, 2017
0ef4311
Add links to other streaming components
clue May 3, 2017
c33d7f1
Add a word of warning regarding fopen() and family
clue May 3, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Add a word of warning regarding fopen() and family
  • Loading branch information
@clue
clue committed May 4, 2017
commit c33d7f10eb8b02bc2a18b5e4ea0b32e5fc78aace
28 changes: 23 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -781,6 +781,14 @@ creating a stream instance.
However, if you are writing a lower-level component or want to create a stream
instance from a stream resource, then the following chapter is for you.

> Note that the following examples use `fopen()` and `stream_socket_client()`
for illustration purposes only.
These functions SHOULD NOT be used in a truly async program because each call
may take several seconds to complete and would block the EventLoop otherwise.
Additionally, the `fopen()` call will return a file handle on some platforms
which may or may not be supported by all EventLoop implementations.
As an alternative, you may want to use higher-level libraries listed above.

### ReadableResourceStream

The `ReadableResourceStream` is a concrete implementation of the
Expand Down Expand Up @@ -1065,17 +1073,27 @@ $through->write(2);
```

## Usage

The following example can be used to pipe the contents of a source file into
a destination file without having to ever read the whole file into memory:

```php
$loop = React\EventLoop\Factory::create();
$loop = new React\EventLoop\StreamSelectLoop::create();

$source = new React\Stream\ReadableResourceStream(fopen('omg.txt', 'r'), $loop);
$dest = new React\Stream\WritableResourceStream(fopen('wtf.txt', 'w'), $loop);
$source = new React\Stream\ReadableResourceStream(fopen('source.txt', 'r'), $loop);
$dest = new React\Stream\WritableResourceStream(fopen('destination.txt', 'w'), $loop);

$source->pipe($dest);
$source->pipe($dest);

$loop->run();
$loop->run();
```

> Note that this example uses `fopen()` for illustration purposes only.
This should not be used in a truly async program because the filesystem is
inherently blocking and each call could potentially take several seconds.
See also [creating streams](#creating-streams) for more sophisticated
examples.

## Install

The recommended way to install this library is [through Composer](http://getcomposer.org).
Expand Down
0