Matcha.Trace (Matcha v0.1.3) View Source

About tracing.

Link to this section Summary

Functions

Checks if pid is awaiting trace messages.

Trace function calls to module with specified arguments.

Trace all function calls to module.

Trace all calls to a module.

Stops all tracing at once.

Link to this section Types

Specs

info_flag() ::
  :send
  | :receive
  | :set_on_spawn
  | :call
  | :return_to
  | :procs
  | :set_on_first_spawn
  | :set_on_link
  | :running
  | :garbage_collection
  | :timestamp
  | :monotonic_timestamp
  | :strict_monotonic_timestamp
  | :arity

Specs

info_item() ::
  :flags
  | :tracer
  | :traced
  | :match_spec
  | :meta
  | :meta_match_spec
  | :call_count
  | :call_time
  | :all

Specs

info_item_result() ::
  {:traced, :global | :local | false | :undefined}
  | {:match_spec, Matcha.Source.spec() | false | :undefined}
  | {:meta, pid() | port() | false | :undefined | []}
  | {:meta, module(), any()}
  | {:meta_match_spec, Matcha.Source.spec() | false | :undefined}
  | {:call_count, non_neg_integer() | boolean() | :undefined}
  | {:call_time,
     [{pid(), non_neg_integer(), non_neg_integer(), non_neg_integer()}]
     | boolean()
     | :undefined}

Specs

info_result() ::
  :undefined
  | {:flags, [info_flag()]}
  | {:tracer, pid() | port() | []}
  | {:tracer, module(), any()}
  | info_item_result()
  | {:all, [info_item_result()] | false | :undefined}

Specs

info_subject() ::
  pid()
  | port()
  | :new
  | :new_processes
  | :new_ports
  | {module(), function :: atom(), arity :: non_neg_integer()}
  | :on_load
  | :send
  | :receive

Specs

t() :: %Matcha.Trace{
  arguments: :any | 0..255 | Matcha.Spec.t(),
  function: atom(),
  limit: pos_integer(),
  module: atom(),
  opts: Keyword.t()
}

Link to this section Functions

Link to this function

awaiting_messages?(pid \\ :all, timeout \\ 5000)

View Source

Specs

awaiting_messages?(:all | pid(), timeout :: non_neg_integer()) :: boolean()

Checks if pid is awaiting trace messages.

Waits timeout milliseconds for the pid to report that all trace messages intended for it when awaiting_messages?/2 was called have been delivered.

Returns true if no response is received within timeout, and you may assume that pid is still working through trace messages it has received. If it receives confirmation before the timeout, returns false.

The pid must refer to an alive (or previously alive) process from the same node this function is called from, or it will raise an ArgumentError.

If the atom :all is provided instead of a pid, this function returns true if any process on the current node is awaiting trace messages.

This function is best used when shutting down processes (or the current node), to give them a chance to finish any tracing they are handling.

Link to this function

calls(module, function, arguments, opts \\ [])

View Source

Specs

Trace function calls to module with specified arguments.

arguments may be:

  • an integer arity, only tracing function calls with that number of parameters
  • a Matcha.Spec, only tracing function calls whose arguments match the provided patterns

If calling with just an arity, all matching calls will print a corresponding trace message. If calling with a spec, additional operations can be performed, as documented in Matcha.Context.Trace.

By default, only 1 calls will be traced. More calls can be traced by providing an integer :limit in the opts.

All other opts are forwarded to :recon_trace.calls/3 as the third argument.

Link to this function

function(module, function, opts \\ [])

View Source

Trace all function calls to module.

By default, only 1 calls will be traced. More calls can be traced by providing an integer :limit in the opts.

All other opts are forwarded to :recon_trace.calls/3 as the third argument.

Link to this function

info(pid_port_func_event, item)

View Source

Specs

Link to this function

module(module, opts \\ [])

View Source

Trace all calls to a module.

By default, only 1 calls will be traced. More calls can be traced by providing an integer :limit in the opts.

All other opts are forwarded to :recon_trace.calls/3 as the third argument.

Stops all tracing at once.