mirai - For Package Authors

1. Developer Interfaces

mirai provides these functions for package authors:

  1. require_daemons() - errors and prompts users to set daemons if not already set (with clickable function link if cli package available)
  2. daemons_set() - detects if daemons are set
  3. on_daemon() - detects if code runs on a daemon (within a mirai() call)
  4. register_serial() - registers custom serialization functions, automatically available for all subsequent daemons() calls
  5. nextget() - queries compute profile values like ‘url’ (see function documentation). Note: only specifically-documented values are supported interfaces.

2. Guidance

mirai supports transparent, inter-operable package use. Not relying on global options or environment variables minimizes conflicts between packages.

Important points:

  1. Leave daemons() settings to end-users. As a package author, assume mirai run on whatever resources users have available. Don’t anticipate whether users run code locally, distributed, or mixed.

    • Point to mirai::daemons() documentation or re-export daemons() for convenience
    • Never call daemons() when using mirai_map() to prevent accidental recursive daemon creation (e.g., if your function is used within another package’s mirai-using function)
      • Exception: Can provide a synchronous fallback if users haven’t set daemons: 
        with(if (!daemons_set()) daemons(sync = TRUE), {
  mirai_map(...)
})
    • Exceptional case: Use daemons(n = 1, dispatcher = FALSE, .compute = ...) for a single dedicated daemon only with a unique .compute value. Example: logger::appender_async() where logger’s ‘namespace’ maps to mirai’s ‘compute profile’.

  2. Don’t use status() programmatically. Its interface may change. Use info() instead.

    • For status()$daemons, use nextget("url")

  3. Use info() programmatically by name, not position. Index by element name (e.g., info()[["cumulative"]]) not position (e.g., info()[[2]]) in case values are added later.

  4. Use official test functions for mirai state. Use unresolved(), is_error_value(), is_mirai_error(), and is_mirai_interrupt().

    • Don’t rely on implementation characteristics (e.g., logical NA for ‘unresolvedValue’) as these may change

  5. CRAN package rules:

    • Use only one daemon with dispatcher = FALSE (stays within 2-core limit)
    • Always reset with daemons(0) at end of examples/test files, then sleep at least 1 second to ensure proper process exit
    • Never modify asyncdial or autoexit defaults for daemon() (or functions passing arguments to it like daemons()). This ensures processes exit with the host process.