Overviewerlang logo

Module lazy

A lazy lib.

Copyright © (C) 2013-2020, Jan Henry Nystrom <JanHenryNystrom@gmail.com> -------------------------------------------------------------------

Authors: Jan Henry Nystrom (JanHenryNystrom@gmail.com).

Description

A lazy lib.

This library provides a simple pull oriented interface towards different data sources using a lazy data abstraction.

The primary use case is the decoding of protocols where the sizes of parts are not known until they have been completely decoded and one wishes to decouple the handling of the data source and the protocol code.

The user of the library provides a promise of data: a function that given a timeout returns either a data or eol (end of lazy) within the timespan given by the timeout. A promise can also have a state in which case the initial state has to be provided with the function. The stateful promise function must retun a tuple of {Data, NewState}. If the timeout is eol is given the promise should return eol and any resources, such as streams and sockets, should be deallocated.

The library provides the functions create/1 and create/2 to create lazy data structures given a promise. The structure can then be applied to a timeout to generate a tuple of data and new lazy data {Data, Lazy} or eol.

Several utility functions are provided to construct new LazyData.

One function is provided that creates an "empty" LazyData empty/0.

Two functions to add a data to existing lazy data are provided: prepend/2 and append/2 that adds the data before or after the lazy data respectively.

One function that combines lazy data is provided: concat/2.

A number of utility funtions are provided, functioning both as simple examples as well as convenience for basic uses: list_to_data/1, iolist_to_data/1 tcp_to_data/2, tcp_to_data/3,tcp_to_data/4, tcp_socket_to_data/1 tcp_reconnect_to_data/3 file_to_data/2, file_stream_to_data/2

N.B. This library relies heavily on the construction of lambda functions and for the sake of clearity and efficiency should be avoided if a more direct approach, that does not suffer heavily from these very drawback itself, exists.

Data Types

data()

data(Type) = fun(([timeout() | eol]) -> {Type, data(Type)}) | eol

promise()

promise(Type, State) = fun(([timeout() | eol], State) -> {Type, State} | eol)

promise()

promise(Type) = fun(([timeout() | eol]) -> Type | eol)

Function Index

append/2 Lazy data is constructed from data and lazy data where when cosumed the data comes after all of the lazy data.
concat/2 Lazy data is constructed from lazy data and lazy data where when cosumed the LazyData1 comes before all the data of of the LazyData2.
create/1 Given a promise, lazy data is created.
create/2 Given a promise and an initial state, stateful lazy data is created.
empty/0 Creates an empty LazyData that just returns eol.
file_stream_to_data/2 A Lazy binary is constructed from the stream, it is expected to be opened in binary raw mode with read_ahead.
file_to_data/2 A Lazy binary is constructed from the stream, when opening the file in binary raw mode with read_ahead.
iolist_to_data/1 A Lazy binary is constructed from an iolist.
list_to_data/1 Lazy data is constructed from a list.
prepend/2 Lazy data is constructed from data and lazy data where when cosumed the data comes before any of the lazy data.
tcp_reconnect_to_data/3 A Lazy binary is constructed from the socket that opening a tcp connetion to the host in binary mode with packet size 0.
tcp_socket_to_data/1 A Lazy binary is constructed from the socket, it is expected to be connected to the host in binary mode with packet size 0.
tcp_to_data/2 A Lazy binary is constructed from the socket that opening a tcp connetion to the host in binary mode with packet size 0.
tcp_to_data/3 A Lazy binary is constructed from the socket that opening a tcp connetion to the host in binary mode with packet size 0.
tcp_to_data/4 A Lazy binary is constructed from the socket that opening a tcp connetion to the host in binary mode with packet size 0.

Function Details

append/2

append(Type, Lazy::data(Type)) -> data(Type)

Lazy data is constructed from data and lazy data where when cosumed the data comes after all of the lazy data.

concat/2

concat(Lazy1::data(Type), Lazy2::data(Type)) -> data(Type)

Lazy data is constructed from lazy data and lazy data where when cosumed the LazyData1 comes before all the data of of the LazyData2.

create/1

create(F::promise(Type)) -> data(Type)

Given a promise, lazy data is created.

create/2

create(F::promise(Type, State), State) -> data(Type)

Given a promise and an initial state, stateful lazy data is created.

empty/0

empty() -> data(term())

Creates an empty LazyData that just returns eol.

file_stream_to_data/2

file_stream_to_data(ChunkSize::line | integer(), Stream::file:io_device()) -> data(binary())

A Lazy binary is constructed from the stream, it is expected to be opened in binary raw mode with read_ahead. On errors reading from the stream results in the closure and eol is returned. The mode determines if the data is read linewise or in chunks of Mode characters.

file_to_data/2

file_to_data(Type::line | integer(), Name::file:filename()) -> data(binary()) | {error, file:posix() | badarg | system_limit}

A Lazy binary is constructed from the stream, when opening the file in binary raw mode with read_ahead. On errors reading from the stream results in the closure and eol is returned. The mode determines if the data is read linewise or in chunks of Mode characters.

iolist_to_data/1

iolist_to_data(List::iolist()) -> data(binary())

A Lazy binary is constructed from an iolist.

list_to_data/1

list_to_data(List::[Type]) -> data(Type)

Lazy data is constructed from a list.

prepend/2

prepend(Type, Lazy::data(Type)) -> data(Type)

Lazy data is constructed from data and lazy data where when cosumed the data comes before any of the lazy data.

tcp_reconnect_to_data/3

tcp_reconnect_to_data(HostName, Port, Timeout::timeout()) -> data(binary())

A Lazy binary is constructed from the socket that opening a tcp connetion to the host in binary mode with packet size 0. If an error occurs during connection an error is returned. If the connection is closed it is reconnected.

tcp_socket_to_data/1

tcp_socket_to_data(Socket::inet:socket()) -> data(binary())

A Lazy binary is constructed from the socket, it is expected to be connected to the host in binary mode with packet size 0. On errors/closure reading from the socket results in the closure and eol is returned. Timeout in reading gives an empty binary.

tcp_to_data/2

tcp_to_data(HostName, Port) -> data(binary()) | {error, inet:posix()}

A Lazy binary is constructed from the socket that opening a tcp connetion to the host in binary mode with packet size 0. If an error occurs during connection an error is returned.

tcp_to_data/3

tcp_to_data(HostName, Port, Timeout::timeout()) -> data(binary()) | {error, inet:posix()}

A Lazy binary is constructed from the socket that opening a tcp connetion to the host in binary mode with packet size 0. If an error or timeout occurs during connection an error is returned.

tcp_to_data/4

tcp_to_data(HostName, Port, Timeout::timeout(), OptionsIn::[gen_tcp:connect_option()]) -> data(binary()) | {error, inet:posix()}

A Lazy binary is constructed from the socket that opening a tcp connetion to the host in binary mode with packet size 0. If an error or timeout occurs during connection an error is returned. If the options provided are inconsistent with: {packet, 0}, binary, {active, false} unexpected and undefined behaviour will be the result.

Overviewerlang logo

Generated by EDoc