IEx.break-exclamation-mark
break-exclamation-mark
, go back to IEx module for more information.
Specs
break!(module(), atom(), arity(), non_neg_integer()) :: IEx.Pry.id()
Sets up a breakpoint in module
, function
and arity
with
the given number of stops
.
This function will instrument the given module and load a new version in memory with breakpoints at the given function and arity. If the module is recompiled, all breakpoints are lost.
When a breakpoint is reached, IEx will ask if you want to pry
the given function and arity. In other words, this works similar
to IEx.pry/0
as the running process becomes the evaluator of
IEx commands and is temporarily changed to have a custom group
leader. However, differently from IEx.pry/0
, aliases and imports
from the source code won't be available in the shell.
IEx helpers includes many conveniences related to breakpoints.
Below they are listed with the full module, such as IEx.Helpers.breaks/0
,
but remember it can be called directly as breaks()
inside IEx.
They are:
IEx.Helpers.break!/2
- sets up a breakpoint for a givenMod.fun/arity
IEx.Helpers.break!/4
- sets up a breakpoint for the given module, function, arityIEx.Helpers.breaks/0
- prints all breakpoints and their IDsIEx.Helpers.continue/0
- continues until the next breakpoint in the same shellIEx.Helpers.open/0
- opens editor on the current breakpointIEx.Helpers.remove_breaks/0
- removes all breakpoints in all modulesIEx.Helpers.remove_breaks/1
- removes all breakpoints in a given moduleIEx.Helpers.reset_break/1
- sets the number of stops on the given ID to zeroIEx.Helpers.reset_break/3
- sets the number of stops on the given module, function, arity to zeroIEx.Helpers.respawn/0
- starts a new shell (breakpoints will ask for permission once more)IEx.Helpers.whereami/1
- shows the current location
By default, the number of stops in a breakpoint is 1. Any follow-up call won't stop the code execution unless another breakpoint is set.
Alternatively, the number of stops can be increased by passing the stops
argument. IEx.Helpers.reset_break/1
and IEx.Helpers.reset_break/3
can be used to reset the number back to zero. Note the module remains
"instrumented" even after all stops on all breakpoints are consumed.
You can remove the instrumentation in a given module by calling
IEx.Helpers.remove_breaks/1
and on all modules by calling
IEx.Helpers.remove_breaks/0
.
To exit a breakpoint, the developer can either invoke continue()
,
which will block the shell until the next breakpoint is found or
the process terminates, or invoke respawn()
, which starts a new IEx
shell, freeing up the pried one.
Examples
The examples below will use break!
, assuming that you are setting
a breakpoint directly from your IEx shell. But you can set up a break
from anywhere by using the fully qualified name IEx.break!
.
The following sets up a breakpoint on URI.decode_query/2
:
break! URI, :decode_query, 2
This call will setup a breakpoint that stops once. To set a breakpoint that will stop 10 times:
break! URI, :decode_query, 2, 10
IEx.break!/2
is a convenience macro that allows breakpoints
to be given in the Mod.fun/arity
format:
break! URI.decode_query/2
Or to set a breakpoint that will stop 10 times:
break! URI.decode_query/2, 10
This function returns the breakpoint ID and will raise if there is an error setting up the breakpoint.
Patterns and guards
IEx.break!/2
allows patterns to be given, triggering the
breakpoint only in some occasions. For example, to trigger
the breakpoint only when the first argument is the "foo=bar"
string:
break! URI.decode_query("foo=bar", _)
Or to trigger it whenever the second argument is a map with more than one element:
break! URI.decode_query(_, map) when map_size(map) > 0
Only a single break point can be set per function. So if you call
IEx.break!
multiple times with different patterns, only the last
pattern is kept.
Note that, while patterns may be given to macros, remember that macros receive ASTs as arguments, and not values. For example, if you try to break on a macro with the following pattern:
break! MyModule.some_macro(pid) when pid == self()
This breakpoint will never be reached, because a macro never receives
a PID. Even if you call the macro as MyModule.some_macro(self())
,
the macro will receive the AST representing the self()
call, and not
the PID itself.
Breaks and mix test
To use IEx.break!/4
during tests, you need to run mix
inside
the iex
command and pass the --trace
to mix test
to avoid running
into timeouts:
iex -S mix test --trace
iex -S mix test path/to/file:line --trace