Reference

Relevant source files

This section provides comprehensive reference material for the mirai package, including the complete function interface, version history, and development information. It serves as a technical lookup resource for package functionality, organized by functional area and purpose.

For conceptual explanations and usage patterns, see the earlier sections: Core Functionality covers the primary evaluation and daemon management APIs, Distributed Computing explains deployment strategies, and Integration and Interoperability documents ecosystem integration. For detailed version-specific information and migration guides, see Version History and Changelog.

Function Organization

The mirai package exports 40 functions and operators, organized into nine functional areas. This structure reflects the layered architecture described in Architecture and Design Philosophy.

Sources: NAMESPACE1-111

Core Functions by Category

Category	Functions	Primary Purpose
Async Evaluation	`mirai()`, `mirai_map()`, `race_mirai()`	Create asynchronous computations
Result Access	`call_mirai()`, `collect_mirai()`, `[]`	Retrieve mirai values
Daemon Control	`daemons()`, `daemon()`, `dispatcher()`	Configure worker processes
Local Launch	`launch_local()`	Spawn daemons on local machine
Remote Launch	`launch_remote()`, `cluster_config()`, `ssh_config()`, `remote_config()`	Deploy daemons to remote resources
Monitoring	`status()`, `info()`	Observe system state
Broadcasting	`everywhere()`	Execute on all daemons
Profile Scoping	`with_daemons()`, `local_daemons()`, `with()`	Manage compute profiles
Error Handling	`is_error_value()`, `is_mirai_error()`, `is_mirai_interrupt()`, `stop_mirai()`, `unresolved()`	Detect and handle errors
Serialization	`serial_config()`, `register_serial()`	Custom object transfer
URL Construction	`host_url()`, `local_url()`	Generate connection URLs
Cluster Backend	`make_cluster()`, `stop_cluster()`	Create miraiCluster objects
Developer Tools	`nextget()`, `nextstream()`, `nextcode()`, `on_daemon()`, `daemons_set()`, `require_daemons()`	Package extension interfaces
Type Checking	`is_mirai()`, `is_mirai_map()`	Object type validation

Sources: NAMESPACE28-64

Object Types and Class Hierarchy

The mirai package defines seven primary object classes with associated S3 methods. Understanding these types is essential for working with the package programmatically.

Sources: NAMESPACE3-24

mirai Object Structure

A mirai object is an environment containing:

$data: The resolved value or an 'unresolvedValue' sentinel
$id: Integer identifier, monotonically increasing per session
Attribute "class": c("mirai", "recvAio")

The object inherits from recvAio (nanonext package), enabling integration with nanonext's async I/O system.

Sources: NEWS.md46

miraiError Components

A miraiError preserves complete error context:

$message: Character string error message
$call: The call that generated the error (srcref stripped)
$stack.trace: List of call objects without deparsing
$condition.class: Original condition classes from error
Additional metadata from rlang::abort() accessible via $

Sources: NEWS.md51-53 NEWS.md175 NEWS.md210

miraiCluster and miraiNode

The miraiCluster class implements the parallel package interface (R >= 4.4):

Inherits from c("miraiCluster", "cluster")
Contains list of miraiNode objects
Methods: parallel::recvData(), parallel::sendData(), parallel::recvOneData(), parallel::stopCluster()
Subset operator <FileRef file-url="https://github.com/r-lib/mirai/blob/128718db/ returns plain list (not miraiCluster)\n\nSources#LNaN-LNaN" NaN file-path="` returns plain list (not miraiCluster)\n\nSources">Hii NEWS.md149-151 NEWS.md328

Method Dispatch System

The package defines 24 S3 methods across 11 generic functions. This enables seamless integration with base R, parallel, and promises ecosystems.

Sources: NAMESPACE3-24

Collection Method Synopsis

The [ operator provides efficient collection for mirai objects:

Usage	Behavior	Equivalent To
`m[]`	Block until resolved, return `$data`	`collect_mirai(m)`
`m_map[]`	Collect all mirai in map	`collect_mirai(m_map)`
`m_map[.progress]`	Collect with progress bar	`collect_mirai(m_map, "progress")`
`m_map[.stop]`	Early stop on first error	`collect_mirai(m_map, "stop")`
`m_map[.flat]`	Flatten results list	`collect_mirai(m_map, "flat")`
`clust[i]`	Extract subset (plain list)	Normal list subsetting

Sources: NAMESPACE4-6 NEWS.md302

Import/Export Interface

The package exports 49 symbols and imports 46 functions from nanonext, its only dependency beyond base R packages.

nanonext Dependency Map

Sources: NAMESPACE65-111

Exported Symbol Categories

The 40 exported symbols break down as:

15 primary functions: Core async evaluation and daemon management (mirai, mirai_map, race_mirai, call_mirai, collect_mirai, daemons, daemon, dispatcher, everywhere, launch_local, launch_remote, status, info, stop_mirai, unresolved)
6 deployment configuration functions: Remote launching and URL construction (cluster_config, ssh_config, remote_config, host_url, local_url, make_cluster)
7 error handling functions: Type checking and error detection (is_error_value, is_mirai, is_mirai_error, is_mirai_interrupt, is_mirai_map, on_daemon, daemons_set)
4 scoping functions: Profile and cluster management (with_daemons, local_daemons, stop_cluster, require_daemons)
3 developer functions: Extension interfaces (nextget, nextstream, nextcode)
2 serialization functions: Custom transfer configuration (serial_config, register_serial)
3 collection options: Map collection flags (.flat, .progress, .stop)

Sources: NAMESPACE25-64

Collection Options System

The mirai_map collection system uses symbol objects to specify options. These are exported constants that enable readable collection syntax.

Symbol	Type	Purpose	Behavior
`.flat`	`miraiCollectFlag`	Flatten results	Avoids coercion when combining heterogeneous types
`.progress`	`miraiCollectFlag`	Progress indication	Shows text progress bar or cli progress (if available)
`.stop`	`miraiCollectFlag`	Early stopping	Returns on first error, cancels remaining tasks

Collection options can be combined: m_map[.stop, .progress] collects with early stopping and progress display.

Sources: NAMESPACE25-27 NEWS.md259

Version and Compatibility

The package maintains semantic versioning aligned with its primary dependency:

mirai 2.5.x (current) requires nanonext >= 1.7.2
mirai 2.x requires nanonext >= 1.4.0
mirai 1.x required nanonext >= 0.8.0
R version: >= 3.6 (current), >= 3.5 historically

Major architectural changes occurred at:

2.5.0: OpenTelemetry tracing, info() function, compute profile helpers
2.0.0: Unified dispatcher architecture, single socket design
1.0.0: Event-driven promises implementation
0.8.0: Compute profiles introduction

Development Version

The current development version includes:

OpenTelemetry 'daemon connect' spans now recorded only after actual connection (#511)
Fix for mirai remaining unresolved when switching from synchronous to dispatcher daemons (#509)

For detailed version history and migration guidance, see Version History and Changelog.

Sources: NEWS.md1-7 NEWS.md8-19 NEWS.md28 NEWS.md44-82 NEWS.md233 NEWS.md330

Developer Extension Points

The package provides three functions specifically for extension developers:

nextget()

Retrieves internal state for daemon processes. Previously supported queries:

nextget("cv"): Returns the condition variable for signaling
nextget("stream"): Returns the current L'Ecuyer-CMRG RNG stream

Note: nextget("pid") was removed in mirai 2.5.1.

Sources: NEWS.md23-36 NEWS.md444

nextstream()

Returns the next L'Ecuyer-CMRG random seed for a given compute profile. Used internally by dispatchers to distribute RNG streams.

Sources: NEWS.md444

nextcode()

Translates integer exit codes from daemon() into human-readable explanations. Exit codes indicate termination reason (normal, timeout, task limit, etc.).

Sources: NEWS.md194

require_daemons()

Prompts users to set up daemons if not already configured. Provides clickable function link when cli package is available.

Signature: require_daemons(.compute, call)

Note: Returns invisibly as intended (fixed in 2.5.2). Argument order was previously (call, .compute) but swapped in 2.5.0 for ease of use.

Sources: NEWS.md8-19 NEWS.md59-74 NEWS.md103-117

Testing and Development Infrastructure

For information on the testing framework, continuous integration workflows, and contribution guidelines, see Testing and Development.

For complete function signatures and detailed parameter documentation, see Function Reference.