ARA strictly separates programming errors from runtime error conditions such as missing files, CPU or I/O overloads etc. Runtime errors occur when accessing external data and resources, which is always done on the host side of the ARA API. Accordingly, the host has the responsibility to detect any such errors and to properly communicate the issue to the user. Since ARA leverages existing technologies, host implementations usually already feature proper code for this. With the error reporting done on the host side, plug-ins do not need to know any details about runtime errors - a simple bool to indicate success or failure is sufficient for implementing normal operation or graceful error recovery. Thus, ARA does not need to define error codes for communicating error details across the API. As an example, consider audio data being read from a server across the network - if the connection breaks, the host will recognize the issue and bring up an according user notification. If the plug-in requests the now inaccessible audio data, the host simply flags that an error occurred and the plug-in can either retry later or use silence as fallback data.
A different kind of errors are programming errors. If either side fails to properly follow the API contract, undefined behavior can occur. Tracking down such bugs from one side only can be difficult and very time consuming, thus ARA strives to aid developers in this process by defining a global assert function that both sides call whenever detecting programming errors related to the ARA API. When debugging (or when running unit tests), either side can provide the code for the assert function, so that no matter what side you're debugging from you can always inject your custom assert handling in order to be able to set proper breakpoints etc. The assert function is only a debug facility: it will usually be disabled on end user systems, and it must never be used for flow control in a shipping product. Instead, each side should implement graceful fallback behavior after asserting the programming error, e.g. by defining a special value for invalid object refs (NULL or -1, depending on the implementation) which will be returned as a placeholder whenever object creation fails due to a programming error on the other side and then filtering this value accordingly whenever objects are referenced.
Typedefs | |
| typedef void(* | ARAAssertFunction) (ARAAssertCategory category, const void *problematicArgument, const char *diagnosis) |
| Global assert function pointer. The assert categories passed to the global assert function are useful both for guiding developers when debugging and for automatic assert evaluation when building unit tests. The diagnosis text is intended solely to aid the developer debugging an issue "from the other side"; they must not be presented to the user (or even parsed for flow control). If applicable (i.e. if the category is kARAAssertInvalidArgument), the diagnosis should contain a hint about what problematicArgument actually points to - for example if a struct is too small, you'd pass the pointer to the struct along with a diagnosis message a la: "someExampleInterfacePointer->structSize < kExampleStructMinSize". Creating such appropriate texts automatically can be easily accomplished by custom assert macros. Finally, problematicArgument should point to the argument that contains the invalid data, so that the developer on that end can quickly identify the problem. If you can't provide a meaningful address for it, e.g. because the category is kARAAssertInvalidThread, pass NULL here. | |
| enum ARAAssertCategory : ARAInt32 |
Hint about the nature of the programming error.
| Enumerator | |
|---|---|
| kARAAssertUnspecified | Not covered by any of the following codes. |
| kARAAssertInvalidArgument | Indicate that the caller passed invalid arguments. |
| kARAAssertInvalidState | Indicate that the call is invalid in the current state. e.g. if a document modification is being made without guarding it properly with ARADocumentControllerInterface::beginEditing() and ARADocumentControllerInterface::endEditing() |
| kARAAssertInvalidThread | Indicate that the call cannot be made on the current thread. |