View Source erlperf_job (erlperf v2.1.0)

Job runner, taking care of init/done, workers added and removed. Works just like a simple_one_for_one supervisor (children are temporary runners). There are two benchmarking modes: continuous (activated by setting non-zero concurrency), and sample-based (activated manually and deactivated after runner does requested amount of iterations).

Job is defined with 4 functions (code map):
  • init/0 - called once when starting the job
  • init_runner/0 - called when starting a runner process, or init_runner/1 that accepts return value from init/0. It is an error to omit init/0 if init_runner/1 is defined, but it is not an error to have init_runner/0 when init/0 exists
  • runner/0 - ignores init_runner/0,1
  • runner/1 - requires init_runner/0,1 return value as initial state, passes it as state for the next invocation (accumulator)
  • runner/2 - requires init_runner/0,1 return value as initial state, passes accumulator as a second argument
  • done/1 - requires init/0 (and accepts its return value)

Link to this section Summary

Functions

Returns the sampling handle for the job.
Executes the runner SampleCount times, returns time in microseconds it took to execute. Similar to timer:tc. Has less overhead compared to continuous benchmarking, therefore can be used even for very fast functions.
Requests this job to stop. Caller should monitor the job process to find our when the job has actually stopped.
Returns the current sample for the job, or undefined if the job has stopped.
Change concurrency setting for this job. Does not reset counting. May never return if init_runner does not return.
Sets job process priority when there are workers running. Worker processes may utilise all schedulers, making job process to lose control over starting and stopping workers. By default, job process sets 'high' priority when there are any workers running. Returns the previous setting.
Returns the source code that was generated for this job.
Starts the benchmark instance. Job starts with no workers, use set_concurrency/2 to start some.
Starts the benchmark instance and links it to caller. Job starts with no workers, use set_concurrency/2 to start some.

Link to this section Types

-type callable() :: mfargs() | [mfargs()] | fun() | fun((term()) -> term()) | string().
-type code_map() ::
    #{runner := callable(), init => callable(), init_runner => callable(), done => callable()}.
-type exec() :: #exec{}.
-type handle() :: {module(), non_neg_integer()}.
-type mfargs() :: {module(), atom(), [term()]}.
-type server_ref() :: gen_server:server_ref().
-type state() :: #erlperf_job_state{}.

Link to this section Functions

-spec concurrency(server_ref()) -> Concurrency :: non_neg_integer().
-spec handle(server_ref()) -> handle().
Returns the sampling handle for the job.
Link to this function

handle_call(_, From, Erlperf_job_state)

View Source
-spec handle_call(term(), {pid(), reference()}, state()) -> {reply, term(), state()}.
Link to this function

handle_info(_, Erlperf_job_state)

View Source
-spec handle_info(term(), state()) -> {noreply, state()}.
Link to this function

measure(JobId, SampleCount)

View Source
-spec measure(server_ref(), SampleCount :: non_neg_integer()) ->
           TimeUs :: non_neg_integer() | already_started.
Executes the runner SampleCount times, returns time in microseconds it took to execute. Similar to timer:tc. Has less overhead compared to continuous benchmarking, therefore can be used even for very fast functions.
-spec request_stop(server_ref()) -> ok.
Requests this job to stop. Caller should monitor the job process to find our when the job has actually stopped.
-spec sample(handle()) -> non_neg_integer() | undefined.
Returns the current sample for the job, or undefined if the job has stopped.
Link to this function

set_concurrency(JobId, Concurrency)

View Source
-spec set_concurrency(server_ref(), non_neg_integer()) -> ok.
Change concurrency setting for this job. Does not reset counting. May never return if init_runner does not return.
Link to this function

set_priority(JobId, Priority)

View Source
-spec set_priority(server_ref(), erlang:priority_level()) -> erlang:priority_level().
Sets job process priority when there are workers running. Worker processes may utilise all schedulers, making job process to lose control over starting and stopping workers. By default, job process sets 'high' priority when there are any workers running. Returns the previous setting.
-spec source(handle()) -> [string()].
Returns the source code that was generated for this job.
-spec start(code_map()) -> {ok, pid()} | {error, term()}.
Starts the benchmark instance. Job starts with no workers, use set_concurrency/2 to start some.
-spec start_link(code_map()) -> {ok, pid()} | {error, term()}.
Starts the benchmark instance and links it to caller. Job starts with no workers, use set_concurrency/2 to start some.
Link to this function

terminate(Reason, Erlperf_job_state)

View Source
-spec terminate(term(), state()) -> ok.