Module machi_cr_client

Erlang API for the Machi client-implemented Chain Replication (CORFU-style) protocol.

Behaviours: gen_server.

Description

Erlang API for the Machi client-implemented Chain Replication (CORFU-style) protocol.

See also the docs for machi_flu1_client for additional details on data types and operation descriptions.

The API here is much simpler than the machi_flu1_client or machi_proxy_flu1_client APIs. This module's API is a proposed simple-but-complete form for clients who are not interested in being an active participant in a Machi cluster and to have the responsibility for Machi internals, i.e., client-side Chain Replication, client-side read repair, client-side tracking of internal Machi epoch & projection changes, etc.

This client is implemented as a long-lived Erlang process using gen_server-style OTP code practice. A naive client can expect that this process will manage all transient TCP session disconnections and Machi chain reconfigurations. This client's efforts are best-effort and can require some time to retry operations in certain failure cases, i.e., up to several seconds during a Machi projection & epoch change when a new server is added to the chain.

Doc TODO: Once this API stabilizes, add all relevant data type details to the EDoc here.

Missing API features

So far, there is one missing client API feature that ought to be added to Machi in the near future: more flexible checksum management.

Add a source annotation to all checksums to indicate where the checksum was calculated. For example,

Client-side checksums would be the "strongest" type of checksum, meaning that any data corruption (of the original data and/or of the checksum itself) can be detected after the client-side calculation. There are too many horror stories on The Net about IP PDUs that are corrupted but unnoticed due to weak TCP checksums, buggy hardware, buggy OS drivers, etc. Checksum versioning is also desirable if/when the current checksum implementation changes from SHA-1 to something else.

Implementation notes

The major operation processing is implemented in a state machine-like manner. Before attempting an operation X, there's an initial operation pre-X that takes care of updating the epoch id, restarting client protocol proxies, and if there's any server instability (e.g. some server is wedged), then insert some sleep time. When the chain appears to have stabilized, then we try the X operation again.

Function name for the pre-X stuff is usually X(), and the function name for the X stuff is usually X2(). (I.e., the X stuff follows after pre-X and therefore has a 2 suffix on the function name.)

In the case of read repair, there are two stages: find the value to perform the repair, then perform the repair writes. In the case of the repair writes, the pre-X function is named read_repair3(), and the X function is named read_repair4().

Function Index

append_chunk/3Append a chunk (binary- or iolist-style) of data to a file with Prefix.
append_chunk/4Append a chunk (binary- or iolist-style) of data to a file with Prefix.
append_chunk_extra/4Append a chunk (binary- or iolist-style) of data to a file with Prefix.
append_chunk_extra/5Append a chunk (binary- or iolist-style) of data to a file with Prefix.
checksum_list/2Fetch the list of chunk checksums for File.
checksum_list/3Fetch the list of chunk checksums for File.
code_change/3
handle_call/3
handle_cast/2
handle_info/2
init/1
list_files/1Fetch the list of all files on the remote FLU.
list_files/2Fetch the list of all files on the remote FLU.
quit/1Quit & close the connection to remote FLU and stop our proxy process.
read_chunk/4Read a chunk of data of size Size from File at Offset.
read_chunk/5Read a chunk of data of size Size from File at Offset.
start_link/1Start a local, long-lived process that will be our steady & reliable communication proxy with the fickle & flaky remote Machi server.
terminate/2

Function Details

append_chunk/3

append_chunk(PidSpec, Prefix, Chunk) -> any()

Append a chunk (binary- or iolist-style) of data to a file with Prefix.

append_chunk/4

append_chunk(PidSpec, Prefix, Chunk, Timeout) -> any()

Append a chunk (binary- or iolist-style) of data to a file with Prefix.

append_chunk_extra/4

append_chunk_extra(PidSpec, Prefix, Chunk, ChunkExtra) -> any()

Append a chunk (binary- or iolist-style) of data to a file with Prefix.

append_chunk_extra/5

append_chunk_extra(PidSpec, Prefix, Chunk, ChunkExtra, Timeout) -> any()

Append a chunk (binary- or iolist-style) of data to a file with Prefix.

checksum_list/2

checksum_list(PidSpec, File) -> any()

Fetch the list of chunk checksums for File.

checksum_list/3

checksum_list(PidSpec, File, Timeout) -> any()

Fetch the list of chunk checksums for File.

code_change/3

code_change(OldVsn, S, Extra) -> any()

handle_call/3

handle_call(Request, From, S) -> any()

handle_cast/2

handle_cast(Msg, S) -> any()

handle_info/2

handle_info(Info, S) -> any()

init/1

init(X1) -> any()

list_files/1

list_files(PidSpec) -> any()

Fetch the list of all files on the remote FLU.

list_files/2

list_files(PidSpec, Timeout) -> any()

Fetch the list of all files on the remote FLU.

quit/1

quit(PidSpec) -> any()

Quit & close the connection to remote FLU and stop our proxy process.

read_chunk/4

read_chunk(PidSpec, File, Offset, Size) -> any()

Read a chunk of data of size Size from File at Offset.

read_chunk/5

read_chunk(PidSpec, File, Offset, Size, Timeout) -> any()

Read a chunk of data of size Size from File at Offset.

start_link/1

start_link(P_srvr_list) -> any()

Start a local, long-lived process that will be our steady & reliable communication proxy with the fickle & flaky remote Machi server.

terminate/2

terminate(Reason, State) -> any()


Generated by EDoc, May 20 2015, 12:58:33.