++ed by:
DMOL AERO
4 non-PAUSE users
Author image Tom Molesworth
and 6 contributors

NAME

Ryu::Buffer - accumulate data

DESCRIPTION

Provides a simple way to push bytes or characters into a buffer, and get them back out again.

Typically of use for delimiter-based or fixed-size protocols.

See also Future::Buffer, if you're dealing exclusively with Future instances and don't need the Ryu::Source functionality then that's likely to be a better option.

METHODS

new

Instantiates a new, empty Ryu::Buffer.

METHODS - Reading data

These methods provide ways of accessing the buffer either destructively (read*) or non-destructively (peek*).

read_exactly

Reads exactly the given number of bytes or characters.

Takes the following parameters:

  • $size - number of characters or bytes to return

Returns a Future which will resolve to a scalar containing the requested data.

read_atmost

Reads up to the given number of bytes or characters - if we have at least one byte or character in the buffer, we'll return that even if it's shorter than the requested $size. This method is guaranteed not to return more than the $size.

Takes the following parameters:

  • $size - maximum number of characters or bytes to return

Returns a Future which will resolve to a scalar containing the requested data.

read_atleast

Reads at least the given number of bytes or characters - if we have a buffer that's the given size or larger, we'll return everything available, even if it's larger than the requested $size.

Takes the following parameters:

  • $size - minimum number of characters or bytes to return

Returns a Future which will resolve to a scalar containing the requested data.

read_until

Reads up to the given string or regex match.

Pass a qr// instance if you want to use a regular expression to match, or a plain string if you want exact-string matching behaviour.

The data returned will include the match.

Takes the following parameters:

  • $match - the string or regex to match against

Returns a Future which will resolve to the requested bytes or characters.

read_packed

Uses pack template notation to define a pattern to extract. Will attempt to accumulate enough bytes to fulfill the request, then unpack and extract from the buffer.

This method only supports a very limited subset of the full pack functionality - currently, this includes sequences such as A4 or N1n1, but does not handle multi-stage templates such as N/a*.

These would need to parse the initial N1 bytes to determine the full extent of the data to be processed, and the logic for handling this is not yet implemented.

Takes the following parameters:

  • $format - a pack-style format string

Returns a Future which will resolve to the requested items, of which there can be more than one depending on the format string.

write

Add more data to the buffer.

Call this with a single scalar, and the results will be appended to the internal buffer, triggering any callbacks for read activity as required.

size

Returns the current buffer size.

is_empty

Returns true if the buffer is currently empty (size = 0), false otherwise.

METHODS - Internal

These are documented for convenience, but generally not recommended to call any of these directly.

data

Accessor for the internal buffer. Not recommended to use this, but if you break it you get to keep all the pieces.

process_pending

Used internally to trigger callbacks once "write" has been called.

new_future

Instantiates a new Future, used to ensure we get something awaitable.

Can be overridden using $Ryu::FUTURE_FACTORY.

INHERITED METHODS

Ryu::Node

completed, describe, flow_control, is_paused, label, parent, pause, resume, unblocked

AUTHOR

Tom Molesworth <TEAM@cpan.org>

LICENSE

Copyright Tom Molesworth 2011-2021. Licensed under the same terms as Perl itself.