IEx.break-exclamation-mark

You're seeing just the function break-exclamation-mark, go back to IEx module for more information.
Link to this function

break!(module, function, arity, stops \\ 1)

View Source (since 1.5.0)

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:

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