aequitas (aequitas v1.4.0)

Copy Markdown View Source

Fairness regulator for Erlang/OTP and Elixir, with optional rate limiting.

aequitas allows fair access to limited external resources (databases, web services, ...) amongst distinct actors, by detecting outliers in ordinary workload distributions. See the README for an overview, configuration and examples.

Summary

Functions

ask(Category, ActorId)

Like ask/3 but with default options.

ask(Category, ActorId, Opts)

Request permission to perform work, identified under ActorId, within Category.

async_ask(Category, ActorId)

Like async_ask/3 but with default options.

async_ask(Category, ActorId, Opts)

Like ask/3 but the reply is sent asynchronously.

reconfigure(Category, SettingOpts)

Tweak settings of work Category.

start(Category)

Like start/2 but with default options.

start(Category, Opts)

Starts a handler for Category.

stop(Category)

Stops a Category handler.

Functions

ask(Category, ActorId)

-spec ask(Category, ActorId) -> Status | {error, Reason}
             when
                 Category :: term(),
                 ActorId :: term(),
                 Status :: accepted | {rejected, RejectionReason},
                 RejectionReason :: outlier | rate_limited,
                 Reason :: not_started.

Like ask/3 but with default options.

See also async_ask/2 and async_ask/3.

ask(Category, ActorId, Opts)

-spec ask(Category, ActorId, Opts) -> Status | {Status, Stats} | {error, Reason}
             when
                 Category :: term(),
                 ActorId :: term(),
                 Opts :: [aequitas_category:ask_opt()],
                 Status :: accepted | {rejected, RejectionReason},
                 RejectionReason :: outlier | rate_limited,
                 Stats :: aequitas_work_stats:t(),
                 Reason :: not_started.

Request permission to perform work, identified under ActorId, within Category.

Returns:

  • accepted if work execution was granted
  • {rejected, Reason} if work execution was denied
  • {error, Reason} if something went wrong

See also ask/2, async_ask/2 and async_ask/3.

async_ask(Category, ActorId)

-spec async_ask(Category, ActorId) -> {Tag, Monitor}
                   when
                       Category :: term(), ActorId :: term(), Tag :: reference(), Monitor :: reference().

Like async_ask/3 but with default options.

See also ask/2 and ask/3.

async_ask(Category, ActorId, Opts)

-spec async_ask(Category, ActorId, Opts) -> {Tag, Monitor}
                   when
                       Category :: term(),
                       ActorId :: term(),
                       Opts :: [aequitas_category:ask_opt()],
                       Tag :: reference(),
                       Monitor :: reference().

Like ask/3 but the reply is sent asynchronously.

Returns a {Tag, Monitor} pair whose members can be used to pattern match against the reply, which will be sent as a message to the calling process in one of the following formats:

  • {Tag, accepted} if work execution was granted
  • {Tag, {rejected, Reason}} if work execution was denied
  • {Tag, {accepted, Stats}} if work execution was granted and stats requested
  • {Tag, {{rejected, Reason}, Stats}} if work execution was denied and stats requested
  • {'DOWN', Monitor, process, _Pid, _Reason} if the handler stopped

In case of a successful reply, don't forget to clean Monitor up, which can be done like this: demonitor(Monitor, [flush]).

See also ask/2, ask/3 and async_ask/2.

reconfigure(Category, SettingOpts)

-spec reconfigure(Category, SettingOpts) -> ok | {error, Reason}
                     when
                         Category :: term(),
                         SettingOpts :: [aequitas_category:setting_opt()],
                         Reason :: not_started | {invalid_setting_opt | invalid_setting_opts, term()}.

Tweak settings of work Category.

Returns:

  • ok in case of success
  • {error, Reason} otherwise

See also start/2 and stop/1.

start(Category)

-spec start(Category) -> ok | {error, Reason} when Category :: term(), Reason :: already_started.

Like start/2 but with default options.

See also stop/1 and reconfigure/2.

start(Category, Opts)

-spec start(Category, Opts) -> ok | {error, Reason}
               when
                   Category :: term(),
                   Opts :: [aequitas_category:setting_opt()],
                   Reason ::
                       already_started | {invalid_setting_opt, term()} | {invalid_setting_opts, term()}.

Starts a handler for Category.

Returns:

  • ok in case of success
  • {error, Reason} otherwise

See also start/1, stop/1 and reconfigure/2.

stop(Category)

-spec stop(Category) -> ok | {error, Reason} when Category :: term(), Reason :: not_started.

Stops a Category handler.

  • Category must correspond to a started handler.

Returns:

  • ok in case of success
  • {error, Reason} otherwise

See also start/1 and reconfigure/2.