Module stream
String streams.
Streams are similar to pipes, but specialized for strings. They serve the same purpose as LTN12, i.e. typically processing input from a socket.
Usage:
local stream = require 'lumen.stream'
Functions
| read (streamd, length) | Read from a stream. |
| read_line (streamd) | Read a line from a stream. |
| write (streamd, s, err) | Write to a stream. |
| set_timeout (streamd, read_timeout, write_timeout) | Change the timeout settings. |
| new (size, read_timeout, write_timeout) | Create a new stream. |
Functions
- read (streamd, length)
-
Read from a stream.
Will block if there is no (or not enough) data to read, until it appears. Also accessible as streamd:read([len])
Parameters:
- streamd the the stream descriptor to read from.
- length optional length of string to be returned.
Returns:
-
a string if data is available, nil,'timeout' on timeout, nil, 'closed', err if
stream is closed and empty (err is the additinal error parameter provided on write when closing).
- read_line (streamd)
-
Read a line from a stream.
Will block if there is not a whole line to return, until it arrives. Also accessible as streamd:read_line()
Parameters:
- streamd the the stream descriptor to read from.
Returns:
-
a string if data is available, nil,'timeout' on timeout, nil, 'closed', err if
stream is closed and empty (err is the additinal error parameter provided on write when closing).
The trailing newline is not included in the returned string.
- write (streamd, s, err)
-
Write to a stream.
Will block when writing to a full stream. Also accessible as streamd:write(s ,err)
Parameters:
- streamd the the stream descriptor to write to.
- s the string to write to the stream. false or nil closes the stream.
- err optional error message to register on stream closing.
Returns:
-
true on success, nil,'timeout' on timeout, nil, 'closed', err if
stream is closed
- set_timeout (streamd, read_timeout, write_timeout)
-
Change the timeout settings.
Can be invoked as streamd:set_timeout(read_timeout, write_timeout)
Parameters:
- streamd the the stream descriptor to configure.
- read_timeout timeout for blocking on stream reading operations. -1 or nil wait forever
- write_timeout timeout for blocking on stream writing operations. -1 or nil wait forever
- new (size, read_timeout, write_timeout)
-
Create a new stream.
Parameters:
- size When the buffered string length surpases this value, following attempts to write will block. nil means no limit.
- read_timeout timeout for blocking on stream reading operations. -1 or nil wait forever timeout
- write_timeout timeout for blocking on stream writing operations. -1 or nil wait forever
Returns:
-
a stream descriptor