Extension

Life Cycle

The life cycle of an extension is divided into the following stages:

1. on_configure

2. on_init

3. on_start

4. on_stop

5. on_deinit

At every stage, the extension has the capability to send messages. If the message sent is a command, the extension can also receive the corresponding result. In other words, there is no stage where message transmission or receiving command results is restricted. This functionality allows extensions to communicate with others seamlessly at all stages, enabling the implementation of interdependencies throughout the entire lifecycle. Each lifecycle stage is associated with a specific callback function, complemented by a corresponding on_xxx_done() function to signify the completion of that particular stage.

Life Cycle Callback	End of Life Cycle Function
on_configure	on_configure_done
on_init	on_init_done
on_start	on_start_done
on_stop	on_stop_done
on_deinit	on_deinit_done

Stage Transition Graph

on_configure

This stage initializes the extension's properties, enabling the get_property API from ten_env to retrieve these values during subsequent lifecycle stages. The on_configure_done() function is invoked to signal the completion of the on_configure stage.

  void on_configure(nyra::nyra_env_t &nyra_env) override {
    // Set the initial values of the extension's properties.
    nyra_env.init_property_from_json(
      R"({
           "_nyra": {
             "uri": "msgpack://127.0.0.1:8001/",
             "log_level": 2
           }
         })", nullptr);
    nyra_env.on_configure_done();
  }

on_init

This stage is responsible for initializing the extension. Until on_init_done() is called, the Nyra runtime queues all incoming messages to the extension, delivering them only once the extension is fully ready. However, results from commands initiated by the extension itself are exempt from this queuing. The Nyra runtime immediately passes such results back to the extension, as the extension is expected to be prepared to handle responses to its own commands, given that these are self-initiated actions.

on_start

This stage signifies the point at which the runtime begins transmitting messages to the extension. While the on_start_done function does not serve a specific operational purpose, it is included for consistency with other lifecycle stages and to simplify the framework's learning curve. Typically, on_start_done is invoked at the conclusion of the on_start callback function. Upon receiving on_start_done(), the Nyra runtime begins delivering messages from other extensions to the initialized extension.

  void on_start(nyra::nyra_env_t &nyra_env) override {
    // Some operations.
    nyra_env.on_start_done();
  }

on_stop

An extension may need to stop in various scenarios, such as when the application or engine hosting it is shutting down. When this occurs, the Nyra runtime invokes the on_stop callback to notify the extension that it has entered the on_stop lifecycle stage. This allows the extension to execute any required termination procedures before shutting down.

on_deinit

Once the extension invokes on_stop_done(), it transitions into the on_deinit stage. During this phase, as the extension's resources may no longer be fully operational, the Nyra runtime ceases delivering messages from other extensions to this one.

Relationship Between Extensions at Different Life Cycle Stages

In essence, extensions have no inherent interdependencies and operate independently, transitioning through their own lifecycle stages autonomously. Any dependencies between extensions must be explicitly managed by the extensions themselves, as the Nyra runtime does not impose any assumptions or provide guarantees in this regard.

For instance, if extension A requires extension B to complete its initialization before finalizing its own, extension A can send a command to extension B during its on_init stage. Once extension B completes its initialization and processes the command, it can respond with a result. Upon receiving the result, extension A can then invoke on_init_done to conclude its initialization.

Interface with NYRA Runtime

Extensions interact with the Nyra runtime primarily through three key interfaces:

1. Lifecycle Callbacks These encompass callbacks such as on_init, on_deinit, on_start, and on_stop, which manage the extension's progression through its lifecycle stages.

2. Callbacks for Receiving Messages These include handlers like on_cmd, on_data, on_audio_frame, and on_video_frame, responsible for processing incoming messages directed to the extension.

3. Functions for Sending Messages These consist of functions such as send_cmd, send_data, send_audio_frame, and send_video_frame, enabling the extension to transmit messages to other components.

Lifecycle Callbacks

The lifecycle stages of an extension and their relationship to message handling are as follows:

During on_init to on_init_done, the extension handles its own initialization. At this stage, it can send messages and receive the results of its own commands but cannot actively receive messages sent by other extensions.

In the on_start to on_start_done phase, the extension transitions to readiness. It can send messages and receive the results of its commands but still does not receive messages actively sent by other extensions. Since properties are initialized during on_configure, actions dependent on these properties can be performed. However, as this phase is still part of the initialization process, restrictions on receiving messages initiated by others reduce the need for additional checks.

After on_start_done and until on_stop_done, the extension enters its active operational phase. During this period, it can send and receive all types of messages and their results without restrictions.

In the final stage, on_deinit to on_deinit_done, the extension manages its deinitialization. Similar to the on_init phase, it can send messages and receive the results of its commands, but it does not actively receive messages sent by other extensions, ensuring a smooth shutdown.

Asynchronous Message Processing in Extensions

Extensions in the Nyra framework handle messages asynchronously, enabling highly efficient utilization of computing resources. When the Nyra runtime delivers a message to an extension through callbacks such as on_cmd, on_data, on_audio_frame, or on_video_frame, the extension is not obligated to process the message immediately within the callback. Instead, it can delegate the processing to other threads, processes, or even external systems, leveraging multi-core architectures and distributed computing environments.

Once processing is complete, the extension can return the results to the Nyra runtime via functions such as send_cmd, send_data, send_audio_frame, or send_video_frame. This asynchronous architecture allows results to be sent only when they are ready, decoupling the message processing timeline from the callback's execution. Consequently, the extension does not need to transmit results back to the runtime before the on_cmd, on_data, on_audio_frame, or on_video_frame callbacks conclude, ensuring flexibility and scalability in message handling.