---
name: "Mojo::IOLoop::Stream"
section: "3pm"
platform: "linux"
package: "libmojolicious-perl"
version: "9.39+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Mojo::IOLoop::Stream"
---

# Mojo::IOLoop::Stream(3pm)

Non-blocking I/O stream

## NAME

Mojo::IOLoop::Stream - Non-blocking I/O stream

## SYNOPSIS

```
  use Mojo::IOLoop::Stream;
  # Create stream
  my $stream = Mojo::IOLoop::Stream->new($handle);
  $stream->on(read => sub ($stream, $bytes) {...});
  $stream->on(close => sub ($stream) {...});
  $stream->on(error => sub ($stream, $err) {...});
  # Start and stop watching for new data
  $stream->start;
  $stream->stop;
  # Start reactor if necessary
  $stream->reactor->start unless $stream->reactor->is_running;
```

## DESCRIPTION

Mojo::IOLoop::Stream is a container for I/O streams used by Mojo::IOLoop.

## EVENTS

Mojo::IOLoop::Stream inherits all events from Mojo::EventEmitter and can emit the following new ones.

### close

```
  $stream->on(close => sub ($stream) {...});
```

Emitted if the stream gets closed.

### drain

```
  $stream->on(drain => sub ($stream) {...});
```

Emitted once all data has been written.

### error

```
  $stream->on(error => sub ($stream, $err) {...});
```

Emitted if an error occurs on the stream, fatal if unhandled.

### read

```
  $stream->on(read => sub ($stream, $bytes) {...});
```

Emitted if new data arrives on the stream.

### timeout

```
  $stream->on(timeout => sub ($stream) {...});
```

Emitted if the stream has been inactive for too long and will get closed automatically.

### write

```
  $stream->on(write => sub ($stream, $bytes) {...});
```

Emitted if new data has been written to the stream.

## ATTRIBUTES

Mojo::IOLoop::Stream implements the following attributes.

### high\_water\_mark

```
  my $size = $msg->high_water_mark;
  $msg     = $msg->high_water_mark(1024);
```

Maximum size of "write" buffer in bytes before "can\_write" returns false, defaults to `1048576` (1MiB).

### reactor

```
  my $reactor = $stream->reactor;
  $stream     = $stream->reactor(Mojo::Reactor::Poll->new);
```

Low-level event reactor, defaults to the `"reactor"` attribute value of the global Mojo::IOLoop singleton. Note that this attribute is weakened.

## METHODS

Mojo::IOLoop::Stream inherits all methods from Mojo::EventEmitter and implements the following new ones.

### bytes\_read

```
  my $num = $stream->bytes_read;
```

Number of bytes received.

### bytes\_waiting

```
  my $num = $stream->bytes_waiting;
```

Number of bytes that have been enqueued with "write" and are waiting to be written.

### bytes\_written

```
  my $num = $stream->bytes_written;
```

Number of bytes written.

### can\_write

```
  my $bool = $stream->can_write;
```

Returns true if calling "write" is safe.

### close

```
  $stream->close;
```

Close stream immediately.

### close\_gracefully

```
  $stream->close_gracefully;
```

Close stream gracefully.

### handle

```
  my $handle = $stream->handle;
```

Get handle for stream, usually an IO::Socket::IP or IO::Socket::SSL object.

### is\_readable

```
  my $bool = $stream->is_readable;
```

Quick non-blocking check if stream is readable, useful for identifying tainted sockets.

### is\_writing

```
  my $bool = $stream->is_writing;
```

Check if stream is writing.

### new

```
  my $stream = Mojo::IOLoop::Stream->new($handle);
```

Construct a new Mojo::IOLoop::Stream object.

### start

```
  $stream->start;
```

Start or resume watching for new data on the stream.

### steal\_handle

```
  my $handle = $stream->steal_handle;
```

Steal "handle" and prevent it from getting closed automatically.

### stop

```
  $stream->stop;
```

Stop watching for new data on the stream.

### timeout

```
  my $timeout = $stream->timeout;
  $stream     = $stream->timeout(45);
```

Maximum amount of time in seconds stream can be inactive before getting closed automatically, defaults to `15`. Setting the value to `0` will allow this stream to be inactive indefinitely.

### write

```
  $stream = $stream->write($bytes);
  $stream = $stream->write($bytes => sub {...});
```

Enqueue data to be written to the stream as soon as possible, the optional drain callback will be executed once all data has been written.

## SEE ALSO

Mojolicious, Mojolicious::Guides, \<https://mojolicious.org\>.