engine_app.c File Reference

#include "engine_app/engine_cmd_msg.h"
#include "engine_app/engine_tlm_msg.h"
#include "juno/ds/queue_api.h"
#include "juno/log/log_api.h"
#include "engine_app/engine_app.h"
#include "juno/macros.h"
#include "juno/memory/pointer_api.h"
#include "juno/sb/broker_api.h"
#include "juno/status.h"
#include "juno/time/time_api.h"
#include <stdlib.h>
#include <unistd.h>

Include dependency graph for engine_app.c:

Functions
static JUNO_STATUS_T	Verify (JUNO_APP_ROOT_T *ptJunoApp)
static JUNO_STATUS_T	OnStart (JUNO_APP_ROOT_T *ptJunoApp)
static JUNO_STATUS_T	OnProcess (JUNO_APP_ROOT_T *ptJunoApp)
static JUNO_STATUS_T	OnExit (JUNO_APP_ROOT_T *ptJunoApp)
JUNO_STATUS_T	EngineApp_Init (ENGINE_APP_T *ptJunoApp, const JUNO_LOG_ROOT_T *ptLogger, const JUNO_TIME_ROOT_T *ptTime, JUNO_SB_BROKER_ROOT_T *ptBroker, JUNO_FAILURE_HANDLER_T pfcnFailureHandler, JUNO_USER_DATA_T *pvFailureUserData)

Variables
static const JUNO_APP_API_T	tEngineAppApi

Function Documentation

EngineApp_Init()

JUNO_STATUS_T EngineApp_Init	(	ENGINE_APP_T *	ptJunoApp,
		const JUNO_LOG_ROOT_T *	ptLogger,
		const JUNO_TIME_ROOT_T *	ptTime,
		JUNO_SB_BROKER_ROOT_T *	ptBroker,
		JUNO_FAILURE_HANDLER_T	pfcnFailureHandler,
		JUNO_USER_DATA_T *	pvFailureUserData
	)

DOC

The Application Init Function

The init function's primary responsibility is to assign dependencies. This function enables the main.c project composition root to pass application dependencies to the application. This function is a concrete implementation because it depends entirely on application specifics.

This function asserts the module pointer exists, assigns the dependency pointers, and finally calls the verification function. The verification function is called last because it assumes the pointers have been instantiated.

OnExit()

static JUNO_STATUS_T OnExit ( JUNO_APP_ROOT_T *  ptJunoApp )

static

DOC

<tt>OnExit</tt>

The OnExit function is typically the last function called in the application. It is used to clean-up globally allocated resources like sockets and file descriptors before the main run-time exits. This application does not have any resources to clean up so it just exits.

OnProcess()

static JUNO_STATUS_T OnProcess ( JUNO_APP_ROOT_T *  ptJunoApp )

static

DOC

<tt>OnProcess</tt>

OnProcess is the main run-loop function of the application. It is called on a periodic basis, typically at a set frequency (like 1Hz, 5Hz, 50Hz, 100Hz, etc).

This is where the main functionality of the application will reside.

DOC In this example we will sleep the application for 500ms to simulate extensive work being done within the application. We will also create a convenience variable to access the pipe's queue API.

DOC For this example we will allocate a buffer to attempt to receive a command from the message pipe. We will then initialize an engine command pointer with the address to our allocated buffer.

DOC We will then get the current timestamp using the time api provided by the project root.

DOC Next we initialize a telemetry message with the current RPM and timestamp. This is done at this step because in the case of an error, we will jump to the exit point with a goto statement so we always publish this telemetry.

DOC We will calculate some artificial noise to simulate an actual sensor measurement.

DOC Next we will attempt to dequeue a command from the software bus. This operation will fail if there is no command in the pipe and will jump to the exit point of this function.

DOC Finally we will add some noise to the current RPM in all cases to simulate a real measurement and publish the telemetry.

OnStart()

static JUNO_STATUS_T OnStart ( JUNO_APP_ROOT_T *  ptJunoApp )

static

DOC

<tt>OnStart</tt>

OnStart is the very first function called in a LibJuno project and is typically called only once. The primary purpose of OnStart is to initialize state variables, perform initialization tasks specific to the application, and allocate global application resources.

DOC Within OnStart we will initialize our command message pipe so we can receive commands. We will also register this pipe with the broker so it can be active.

DOC For this example we will also set the current RPM to 0

Verify()

static JUNO_STATUS_T Verify ( JUNO_APP_ROOT_T *  ptJunoApp )

inlinestatic

DOC Next we need to implement the application. engine_app.c will act as a composition root for application specific logic. This means that the application can own some dependencies, like its message buffers and pipes. The line between dependencies an application should own and dependencies the main.c root should own is fuzzy. It depends on developers specific use cases. In general, items like the pipes, memory buffers, and application specific dependencies should be owned by the application. Dependencies that reach to more than one application should be owned by the project composition root (main.c).

Application Api

As stated previously, LibJuno applications are derived from the JUNO_APP_ROOT_T. This means we need to implement the API defined by the root module. We forward declare the api functions and the verification function so we can check and verify that the pointer being passed to our function is in fact a ENGINE_APP_T type by asserting that the api pointers match.

DOC

Verification Function

The verification function is called as the one of the very first lines in a LibJuno API function. Its purpose is to assert that the module contract is met. This means that pointers are initialized, and the APIs match.

In LibJuno we can use JUNO_ASSERT macros that will check for certain common conditions like null pointers. These macros will automatically return JUNO_STATUS_ERR or JUNO_STATUS_NULLPTR_ERROR on failure.

Variable Documentation

tEngineAppApi

const JUNO_APP_API_T tEngineAppApi

static

Initial value:

= {
    .OnStart = OnStart,
    .OnProcess = OnProcess,
    .OnExit = OnExit
}