Recoverable Aborts

mi_par_abort
mi_par_aborted
mi_par_register_abortcallback

Recoverable Aborts

When raylib is performing complex operations (mainly tessellating geometry or rendering the scene from within mi_par_run) it can be aborted. Aborting means that the current function returns as fast as possible without completing the task. This may leave objects untessellated, pixels unrendered, and so on. But unlike a call to mi_fatal all data remains in a clean state so the operation can be done again later. This is intended for Cancel or Abort buttons in the user interface of applications that raylib is built into.

mi_par_abort

void mi_par_abort(
    int             bitmap)

Clear or set the current abort status. If bitmap is 0, clear all abort status; this should be done when an operation has completed aborting and returned to the application that has caused the abort. If bitmap is a small integer, bitwise-OR it to the system abort bitmap; otherwise bitwise-AND it with the system abort bitmap. This can be used to set and clear individual bits. For example, the user abort is set with 1 and cleared with ~1. There are four bits defined in the bitmap:

Bit 0: Application abort (user pressed an abort button). This is the only bit that should be used by raylib client applications (and only raylib clients, it should not be used by raylib itself).
Bit 1: Intra-raylib aborts that tells all threads that all tasks are finished and they can stop now. This is necessary because near the end threads will dequeue in-progress tasks, and as soon as the last in-progress task is finished the threads that are also working on the same task need to be killed without doing an application abort, which may be pending and may not be reset.
Bit 2: All threads are shutting down.
Bit 3: Caught a fatal signal, shutting down.

The new system abort bitmap is broadcast to all connected hosts. If any bits in the system abort map have been set, mi_par_aborted will from then on return nonzero. When the abort is complete and execution returns to the mainline after all threads have terminated, mi_par_abort must be called to clear the relevant bits.

mi_par_aborted

int mi_par_aborted(void)

Every function that uses a large amount of time must periodically call mi_par_aborted and clean up and return if it returns miTRUE. Cleaning up includes releasing memory, locks, and other static information to return them to a state where the operation can be retried later. For example, a long-running output shader might use this call once for every scanline it completes, and break out of the scanline loop if nonzero is returned.

mi_par_register_abortcallback

void mi_par_register_abortcallback(
    miBoolean       (*callback)(void))

This function registers a callback function that will be called by raylib whenever mi_par_aborted is called. The callback function may return miTRUE to abort raylib, as if mi_par_abort had been called. The number of calls to callback is limited to one per second for performance reasons. The purpose of the callback is to allow non-multithreaded applications that raylib is built into to periodically check whether the user has pressed a Cancel or Abort button. Multithreaded applications should use mi_par_abort from another thread instead of the abort callback because there is a small performance penalty involved in polling abort buttons.