View Source wait_helper (wait_helper v0.2.1)

Helper module to implement waiting conditions.

It periodically queries and validates values from a callback until the condition is met or a timeout passes.

Common method when testing for eventual consistency.

Summary

Types

callback/1

A function that returns a value to verify.

history/0

History of results.

name/0

Condition name, defaults to timeout.

opts/1

return/1

sleep_time/0

How long to wait between queries for new results.

validator/1

Validation to do against the callbacks return value.

wait_error/1

An error type that can be returned or thrown when the condition eventually fails.

Functions

wait_until(Fun, Expected)

Waits for Fun to return ExpectedValue.

wait_until(Fun, Expected, Opts)

Waits for Fun to return a value validator accepts.

Types

callback/1

-type callback(Expected) :: fun(() -> Expected | term()).

A function that returns a value to verify.

By default, the return value will be checked for equality against the expected value, but a custom validator/1 function can be specified.

The return value of this callback is what will be returned by the whole wait_until operation.

history/0

-type history() :: [term()].

History of results.

Note that this history will be simplified, that is, if elements repeat consecutively, they will be agregated to the history only once together with a count.

name/0

-type name() :: atom().

Condition name, defaults to timeout.

opts/1

-type opts(Expected) ::
          #{validator => validator(Expected),
            expected_value => Expected,
            time_left => timeout(),
            sleep_time => sleep_time(),
            on_error => fun(() -> term()),
            no_throw => boolean(),
            name => name()}.

return/1

-type return(Expected) :: {ok, Expected} | {error, wait_error(Expected)} | no_return().

sleep_time/0

-type sleep_time() :: non_neg_integer().

How long to wait between queries for new results.

validator/1

-type validator(Expected) :: fun((Expected | term()) -> boolean()).

Validation to do against the callbacks return value.

This is useful when an intermediate value of the callback is desired in the return value, but the condition to be checked requires further computation that is not needed outside of the scope of the condition.

For example:

  Validator = fun(ReturnValue) -> contains(ReturnValue, ...) end,
  {ok, Result} = mongoose_helper:wait_until(
              fun() -> do_get_value(...) end,
              expected,
              #{validator => Validator}),

where Result is the return value of the original callback, after we know it is accepted by the validator

wait_error/1

-type wait_error(Expected) :: {name(), Expected, history(), undefined | term()}.

An error type that can be returned or thrown when the condition eventually fails.

The last element of the tuple is the return value of the on_error callback given to opts/1, if given, otherwise undefined.

Functions

wait_until(Fun, Expected)

-spec wait_until(callback(Expected), Expected) -> return(Expected).

Waits for Fun to return ExpectedValue.

See also: wait_until/3.

wait_until(Fun, Expected, Opts)

-spec wait_until(callback(Expected), Expected, opts(Expected)) -> return(Expected).

Waits for Fun to return a value validator accepts.

If the result of Fun equals ExpectedValue, returns {ok, ExpectedValue}
If no value is returned or the result doesn't equal ExpectedValue:

If no_throw => true is given, it returns {error, Error}, where Error is of type wait_error/1.
If throws the following error: wait_error/1.

Example:

  Opts = #{no_throw => true, time_left => timer:seconds(2)},
  {error, _} = wait_until(fun() -> ... end, SomeVal, Opts)