Cauldron is a multi-threaded Python program. Threads are necessary for the concurrent execution and control of steps. The problem is that Python threads have no safe way of aborting before they are done executing from outside of the thread. This limitation is one of the reasons that the kernel can be so unstable in Python notebooks.

To get around that Cauldron calls a breathe function regularly during the execution of a step whenever a Cauldron display function is called. This breathe function momentarily pauses the execution of the step and checks to see if the thread should be aborted. If the user has indicated that the thread should stop running, the breathe function stops the thread safely inside the thread.

Occasionally you might find yourself running a long-running step without calling any Cauldron display functions. In those cases, aborting the step can only be done in the unsafe way, which can cause your notebooks to become unstable. This breathe function gets around that by letting you call it whenever you chose within the notebook.

Consider a case where you have a long running task. Perhaps it's the loading of a lot of data or an expensive computation. In this example we'll simulate that with Python's time.sleep() function, which halts execution for the specified number of seconds before continuing.

In this example we'll sleep for 10 seconds:

However, long-running tasks are rarely monolithic. Usually they are a collection of shorter running tasks that take a long time when run together. So a better example would be sleeping for 1 second ten times:

Now if we ran the above example in a notebook and then decided we wanted to stop it before it was finished, the only way for Python to abort the execution would be to unsafely kill the thread from the outside.

This is where the breathe function is useful. If we modify the code above to include a call to breathe() on each iteration of the loop:

then the breathe function could handle aborting the thread safely from inside should you choose to stop the function prematurely at any point. This is only necessary if you don't call any Cauldron display functions during the long-running task. If you had done something like this:

no breathe call would be necessary because Cauldron called it internally as part of the call the display function. So the breathe function is only needed in those rare cases of long-running tasks without any display function calls.