Behaviour for implementing values for sregulator.

  -callback init(InternalMap :: internal_map(), Time :: integer(),
                 Args :: any()) ->
       {Status :: open | closed, State :: any(),
        TimeoutTime :: integer() | infinity}.

InternalMap is the internal map of running processes, it is a map() with monitor reference() keys and pid() value where the monitor is that of the process.

Time is the time, in native time units, of the valve at creation. Some other callbacks will receive the current time of the valve as the second last argument. It is monotically increasing, so subsequent calls will have the same or a greater time.

Args is the arguments for the valve. It can be any term.

Status is whether the valve accepts new requests or not. The handle_ask/4 callback to handle a request will only be called when the previous callback returns open.

State is the state of the queue and used in the next call.

TimeoutTime represents the next time a valve wishes to call handle_timeout/2 to change status. If a message is not received the timeout should occur at or after TimeoutTime. The time must be greater than or equal to Time. If a valve does not require a timeout then TimeoutTime should be infinity.

  -callback handle_ask(Ref :: reference(), Pid :: pid(), Time :: integer(),
                       State :: any()) ->
       {go, Open, Status :: open | closed, NState :: any(),
        TimeoutTime :: integer() | infinity}.

Ref is a monitor reference of the sender, Pid, as in the InternalMap in init/3.

Open is the time the valve opened to allow this request.

The other variables are equivalent to those in init/3, with NState being the new state.

  -callback handle_done(Ref :: reference(), Time :: integer(),
                        State :: any()) ->
       {Result :: done | error, Status :: open | closed, NState :: any(),
        TimeoutTime :: integer() | infinity}.

Result is done when the Ref is known by the valve and is removed, if Ref is not found in the valve it is error.

The other variables are equivalent to those in handle_ask/4.

When a request is asking to continue, handle_continue/3: -callback handle_continue(Ref :: reference(), Time :: integer(), State :: any()) -> {Result :: go, Open :: integer(), , Status :: open | closed, NState :: any(), TimeoutTime :: integer() | infinity} | {Result :: done | error, Status :: open | closed, NState :: any(), TimeoutTime :: integer() | infinity}. '''

Result is go if Ref is known by the valve and is allowed to continue, if Ref is removed from the valve it is done and if Ref is not found in the valve it is error.

The other variables are equivalent to those in handle_ask/3.

  -callback handle_info(Msg :: any(), Time :: integer(), State :: any()) ->
      {Status :: open | closed, NState :: any(),
       TimeoutTime :: integer() | infinity}.

Msg is the message, and may be intended for another callback.

The other variables are equivalent to those in init/3, with NState being the new state.

  -callback handle_timeout(Time :: integer(), State :: any()) ->
      {Status :: open | closed, NState :: any(),
       TimeoutTime :: integer() | infinity}.

The variables are equivalent to those in init/3, with NState being the new state.

  -callback code_change(OldVsn :: any(), Time :: integer(), State :: any(),
                        Extra :: any()) ->
       {NState :: any(), TimeoutTime :: integer() | infinity}.

On an upgrade OldVsn is version the state was created with and on an downgrade is the same form except {down, OldVsn}. OldVsn is defined by the vsn attribute(s) of the old version of the callback module. If no such attribute is defined, the version is the checksum of the BEAM file. Extra is from {advanced, Extra} in the update instructions.

The other variables are equivalent to those in init/3, with NState being the new state.

  -callback config_change(Args :: any(), Time :: integer(), State :: any()) ->
       {Status :: open | closed, NState :: any(),
        TimeoutTime :: integer() | infinity}.

The variables are equivalent to those in init/3, with NState being the new state.

  -callback size(State :: any()) -> Size :: non_neg_integer().

State is the current state of the valve and Size is the number of tasks being monitorred. This callback must be idempotent and not change the status of the valve.

  -callback open_time(State :: any()) -> OpenTime :: integer() | closed.

State is the current state of the valve and OpenTime is the open time of the valve, if closed and will not open without a side effect then closed.

  -callback terminate(Reason :: sbroker_handlers:reason(), State :: any()) ->
       InternalMap :: internal_map().

Reason is stop if the valve is being shutdown, change if the valve is being replaced by another valve, {bad_return_value, Return} if a previous callback returned an invalid term or {Class, Reason, Stack} if a previous callback raised an exception.

State is the current state of the valve.

InternalMap is the same as init/3 and is passed to the next valve if Reason is change.