Documentation menu

Runtime and Surface Lifecycle

Coordinate the JavaScript runtime, native event loop, and one session for each Hera surface.

A native session begins when the executable parses its launch options and creates a HeraClient. MainLoop then coordinates transport and mounting progression, while each surface session brings together the Hera surface, Fabric runtime, and retained mounting state needed for one application surface.

Startup and Dispatch Ordering

The main loop initializes mount dispatch and an epoll-based event loop, sends the hello and create-surface requests, and tracks a startup deadline. Unsolicited surface or input traffic does not enter a partially initialized session.

The epoll loop waits on both the client descriptor and the mount dispatcher's eventfd, allowing new mounting work to wake native processing without blocking the JavaScript thread. One eventfd read consumes the aggregate wake count. Returning to the loop after that read prevents continuous mount activity from starving socket traffic.

Session Creation and Resizing

When surface creation completes, SurfaceController builds the session's runtime and root scene. Later SurfaceChanged messages update its authoritative dimensions and the corresponding layout constraints passed to React Native, allowing the application to respond to its actual composed size.

The bundle's registered component name identifies the application root. It must match the name passed through --component.

Mounting and Commit Progress

Fabric can enqueue mounting transactions from its own execution context while the native loop continues handling messages. The dispatcher drains those transactions into the surface's sink, which holds a candidate until retained acceptance resolves it. A later GPU CommitAck reports submission progress rather than replacing that retained outcome.

The main loop includes pending outcome deadlines in its epoll wait. A missing outcome must eventually become a session failure even when no new socket message arrives to wake the loop.

Session Teardown

Destroying a surface unregisters its dispatch path and shuts down the associated session; the loop can stop once no sessions remain. Protocol errors or mounting failures also terminate the affected progression so that an ambiguous retained baseline cannot continue receiving dependent work.

Message-owned strings and touch lists are released after dispatch by the event loop's cleanup guard. Do not retain borrowed FFI pointers past that lifetime without copying their data.

See Fabric mounting and FFI boundary.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • react-native/rn_host/src/platform/core/main_loop.cpp
  • react-native/rn_host/src/platform/core/hera_event_loop.cpp
  • react-native/rn_host/src/platform/session/surface_controller.cpp
  • react-native/rn_host/src/runtime/instance/react_host.cpp