---
title: "For Package Authors"
vignette: >
  %\VignetteIndexEntry{For Package Authors}
  %\VignetteEngine{litedown::vignette}
  %\VignetteEncoding{UTF-8}
---



### 1. Developer Interfaces

mirai offers the following functions primarily for package authors using mirai:

1. `require_daemons()` will error and prompt the user to set daemons (with a clickable function link if the cli package is available) if daemons are not already set.
1. `daemons_set()`, to detect if daemons have already been set and prompt the user to set daemons if not.
1. `on_daemon()`, to detect if code is already running on a daemon, i.e. within a `mirai()` call.
1. `register_serial()` to register custom serialization functions, which are automatically available by default for all subsequent `daemons()` calls.
1. `nextget()`, for querying values for a compute profile, such as 'url', described in the function's documentation. Note: only the specifically-documented values are supported interfaces.

### 2. Guidance

mirai as a framework is designed to support completely transparent and inter-operable use within packages.
A core design precept of not relying on global options or environment variables minimises the likelihood of conflict between use by different packages.

There are hence only a few important points to note:

1. `daemons()` settings should wherever possible be left to end-users.
This means that as a package author, you should just consider that mirai are run on whatever resources are available to the user at the time the code is run.
You do not need to anticipate whether an end-user will run the code on their own machine, distributed over the network, or a mixture of both.

- Consider pointing to the documentation for `mirai::daemons()`, or re-exporting `daemons()` in your package as a convenience.
- Never include a call to `daemons()` when using `mirai_map()`.
  This is important to ensure that there is no accidental recursive creation of daemons on the same machine, for example if your function is used within another package's function that also uses mirai.
- Exceptionally, a `daemons(n = 1, dispatcher = FALSE, .compute = ...)` call may be used to set up a single dedicated daemon, but only if used with a unique value for `.compute`.
  A representative example of this usage pattern is `logger::appender_async()`, where the logger package's 'namespace' concept maps directly to mirai's 'compute profile'.

2. The shape and contents of a `status()` call must not be used programmatically, as this user interface is subject to change at any time. Use `info()` instead.
- For the value of `status()$daemons`, instead use `nextget("url")`.

3. `info()` may be used programmatically, but only index into the vector using the name rather than position e.g. `info()[["cumulative"]]` rather than `info()[[2]]`. This is in case other values are added at a later date.

4. The functions `unresolved()`, `is_error_value()`, `is_mirai_error()`, and `is_mirai_interrupt()` should be used to test for the relevant state of a mirai or its value.
- The characteristics of their current implementation, e.g. as a logical NA for an 'unresolvedValue', should not be relied upon, as these are subject to change at any time.

5. For CRAN packages, all examples and tests should respect the following rules when running on CRAN:
- Use only one daemon (with `dispatcher = FALSE`) to ensure that only one additional process is used, to remain within the 2-core limit.
- Always reset daemons with `daemons(0)` at the end of each example or test file. Then allow at least a one-second sleep to ensure that all background processes have properly exited and that no 'detritus' from the processes remains.
- Never modify the default value of `asyncdial` or `autoexit` for `daemon()`, in that function or any functions that pass arguments through to it such as `daemons()`. This is to ensure that processes exit as soon as the host process does.
