dist_agent v0.1.1 DistAgent.Behaviour behaviour View Source

Behaviour module for distributed agents.

The 6 callbacks are classified into the following 2 dimensions:

  • how the callback is used, i.e., for pure manipulation of state or for side effect
  • when the callback is used, i.e., type of event that triggers the callback

The following table summarizes the classification:

for pure state manipulationfor side effect
used when DistAgent.query/5 is calledhandle_query/2after_query/3
used when DistAgent.command/5 is calledhandle_command/2after_command/4
used when a low-resolution timer fireshandle_timeout/2after_timeout/3

Link to this section Summary

Callbacks

Invoked after handle_query/2

Invoked to handle an incoming command

Invoked to handle an incoming read-only query

Invoked when a low-resolution timer fires

Link to this section Types

Link to this type command() View Source
command() :: any()
Link to this type milliseconds_since_epoch() View Source
milliseconds_since_epoch() :: pos_integer()

Link to this section Callbacks

Link to this callback after_command(data_before, command, ret, data_after) View Source
after_command(
  data_before :: nil | data(),
  command :: command(),
  ret :: ret(),
  data_after :: nil | data()
) :: any()

Invoked after handle_command/2.

Implementations of this callback can have side effects. Note that this callback should avoid long running operations to keep distributed agents responsive; delegate such operations to other processes instead.

The callback takes the following arguments:

  • 1st argument is the state of the distributed agent before the command is applied. This is nil if the agent is right after its activation.
  • 2nd argument is the command passed to the DistAgent.command/5.
  • 3rd argument is the return value to the client process (1st element of return value of handle_command/2).
  • 4th argument is the state of the distributed agent after the command is applied (2nd element of return value of handle_command/2).

Return value of this callback is neglected.

Link to this callback after_query(data, query, ret) View Source
after_query(data(), query(), ret()) :: any()

Invoked after handle_query/2.

Implementations of this callback can have side effects. Note that this callback should avoid long running operations to keep distributed agents responsive; delegate such operations to other processes instead.

The callback takes the following arguments:

  • 1st argument is the state of the distributed agent.
  • 2nd argument is the query passed to the DistAgent.query/5.
  • 3rd argument is the return value to the client process, computed by handle_query/2.

Return value of this callback is neglected.

Link to this callback after_timeout(data_before, now_millis, data_after) View Source
after_timeout(
  data_before :: data(),
  now_millis :: milliseconds_since_epoch(),
  data_after :: nil | data()
) :: any()

Invoked after handle_timeout/2.

Implementations of this callback can have side effects. Note that this callback should avoid long running operations to keep distributed agents responsive; delegate such operations to other processes instead.

The callback takes the following arguments:

  • 1st argument is the state of the distributed agent before the timeout.
  • 2nd argument is the same timestamp passed to handle_timeout/2.
  • 3rd argument is the state of the distrubuted agent after the timeout (1st element of return value of handle_timeout/2).

Return value of this callback is neglected.

Link to this callback handle_command(arg0, command) View Source
handle_command(nil | data(), command()) ::
  {ret(), nil | data(), DistAgent.OnTick.t() | :keep}

Invoked to handle an incoming command.

Implementations of this callback must be pure.

The callback takes the following arguments:

  • 1st argument is the state of the distributed agent. This is nil if the agent is right after its activation.
  • 2nd argument is the command passed to the DistAgent.command/5.

Return value of this callback must be a 3-tuple.

  • 1st element is returned to the caller of DistAgent.command/5.
  • 2nd element is the state after the command is applied; if this value is nil then the distributed agent is deactivated.
  • 3rd element specifies what happens at the subsequent ticks. You may specify either DistAgent.OnTick.t/0 or :keep, where :keep respects the previously set DistAgent.OnTick.t/0.
Link to this callback handle_query(data, query) View Source
handle_query(data(), query()) :: ret()

Invoked to handle an incoming read-only query.

Implementations of this callback must be pure.

The callback takes the following arguments:

  • 1st argument is the state of the distributed agent.
  • 2nd argument is the query passed to the DistAgent.query/5.

Return value of this callback is delivered to the caller process of DistAgent.query/5.

Link to this callback handle_timeout(data, milliseconds_since_epoch) View Source
handle_timeout(data(), milliseconds_since_epoch()) ::
  {nil | data(), DistAgent.OnTick.t()}

Invoked when a low-resolution timer fires.

Implementations of this callback must be pure.

The callback takes the following arguments:

  • 1st argument is the state of the distributed agent.
  • 2nd argument is the current time (milliseconds since UNIX epoch) in UTC time zone. Note that this value is not at all accurate as it’s obtained by the DistAgent.TickSender process.

Return value of this callback must be a 2-tuple.

  • 1st element is the state after the timeout; if this value is nil then the distributed agent is deactivated.
  • 2nd element specifies what happens at the subsequent ticks. See DistAgent.OnTick.t/0 for more details.