Module system and DI

Macros
#define	JUNO_MODULE_DECLARE(NAME_T)   typedef union NAME_T NAME_T
	Forward-declare a Juno module union type.
#define	JUNO_MODULE_ROOT_DECLARE(NAME_T)   typedef struct NAME_T NAME_T
	Forward-declare a module root struct type.
#define	JUNO_MODULE_DERIVE_DECLARE(NAME_T)   JUNO_MODULE_ROOT_DECLARE(NAME_T)
	Forward-declare a derived module struct type.
#define	JUNO_FAILURE_HANDLER   _pfcnFailureHandler
	Member name alias for a module's failure handler.
#define	JUNO_FAILURE_USER_DATA   _pvFailureUserData
	Member name alias for failure handler user data.
#define	JUNO_MODULE_EMPTY
	Helper for module definitions with no additional members.
#define	JUNO_MODULE_ARG(...)   __VA_ARGS__
	Pass-through argument pack helper for module macros.
#define	JUNO_MODULE_SUPER   tRoot
	Standard member name for the embedded module root.
#define	JUNO_MODULE(API_T, ROOT_T, ...)
	Define a module union consisting of the root and all derivations.
#define	JUNO_MODULE_ROOT(API_T, ...)
	Implement a module root struct containing ptApi and failure fields.
#define	JUNO_TRAIT_ROOT(API_T, ...)
	Define a trait root carrying only the API pointer and members.
#define	JUNO_MODULE_DERIVE(ROOT_T, ...)
	Implement a derived module embedding the root as the first member.
#define	JUNO_TRAIT_DERIVE(ROOT_T, ...)   JUNO_MODULE_DERIVE(ROOT_T, __VA_ARGS__)
	Alias to define a trait derivation with the standard layout.
#define	JUNO_MODULE_GET_API(ptModule, ROOT_T)   ((const ROOT_T *)ptModule)->ptApi
	Retrieve the API pointer from a module (via its root view).
#define	JUNO_MODULE_RESULT(NAME_T, OK_T)
	Define a result type combining a status and a success payload.
#define	JUNO_OK(result)   result.tOk
	Access the success payload from a result produced by JUNO_MODULE_RESULT.
#define	JUNO_ASSERT_OK(result, ...)   JUNO_ASSERT_SUCCESS(result.tStatus, __VA_ARGS__)
	Execute the provided statements if result.tStatus is not success.
#define	JUNO_OK_RESULT(value)   {JUNO_STATUS_SUCCESS, value}
	Construct a result indicating success with the provided payload.
#define	JUNO_ERR_RESULT(err, value)   {err, value}
	Construct a result indicating error with a payload (may be default-initialized).
#define	JUNO_MODULE_OPTION(NAME_T, SOME_T)
	Define an option type combining a presence flag and a payload.
#define	JUNO_SOME(result)   result.tSome
	Access the payload from an option produced by JUNO_MODULE_OPTION.
#define	JUNO_ASSERT_SOME(result, ...)
	Execute the provided statements if result.bIsSome is false.
#define	JUNO_SOME_OPTION(value)   {true, value}
	Construct an option in the present state with the provided payload.
#define	JUNO_NONE_OPTION(default_value)   {false, default_value}
	Construct an option in the empty state, carrying a default payload.

Detailed Description

LibJuno implements dependency injection (DI) via a small module system. A module consists of:

• A module root: common, freestanding members shared by all implementations.
• One or more derived implementations: embed the root as their first member and add implementation-specific state and dependencies.
• A module union: a union of the root and all derived implementations, enabling safe up-casts to the root.

Key properties:

• Every derived implementation starts with the root, allowing safe up-casts to the root type for API dispatch and failure handling.
• The root contains ptApi and failure handler fields and should avoid hosted dependencies to preserve freestanding portability.
• APIs (vtables) receive a pointer to the root (or compatible view) for dispatch.

Example (defining a module union):

union MY_MODULE_T JUNO_MODULE(MY_MODULE_API_T, MY_MODULE_ROOT_T,
    MY_MODULE_DERIVATION_1_T;
    MY_MODULE_DERIVATION_2_T;
    MY_MODULE_DERIVATION_3_T;
);

Macro Definition Documentation

JUNO_ASSERT_OK

#define JUNO_ASSERT_OK	(		result,
			...
	)		JUNO_ASSERT_SUCCESS(result.tStatus, __VA_ARGS__)

Execute the provided statements if result.tStatus is not success.

This is a convenience wrapper over JUNO_ASSERT_SUCCESS. Typical usage:

MY_RESULT_T r = DoThing();
JUNO_ASSERT_OK(r, return r.tStatus);
use(JUNO_OK(r));

JUNO_ASSERT_SOME

#define JUNO_ASSERT_SOME	(		result,
			...
	)

Value:

    if(!result.bIsSome){ \
    __VA_ARGS__  \
}

Execute the provided statements if result.bIsSome is false.

Typical usage:

MY_OPTION_T o = MaybeGet();
JUNO_ASSERT_SOME(o, return JUNO_STATUS_DNE_ERROR);
use(JUNO_SOME(o));

JUNO_ERR_RESULT

#define JUNO_ERR_RESULT	(		err,
			value
	)		{err, value}

Construct a result indicating error with a payload (may be default-initialized).

JUNO_FAILURE_HANDLER

#define JUNO_FAILURE_HANDLER   _pfcnFailureHandler

Member name alias for a module's failure handler.

JUNO_FAILURE_USER_DATA

#define JUNO_FAILURE_USER_DATA   _pvFailureUserData

Member name alias for failure handler user data.

JUNO_MODULE

#define JUNO_MODULE	(		API_T,
			ROOT_T,
			...
	)

Value:

{ \
    ROOT_T JUNO_MODULE_SUPER; \
    __VA_ARGS__ \
}

Define a module union consisting of the root and all derivations.

Parameters

API_T	The API (vtable) type for the module.
ROOT_T	The root struct type for the module.
...	One or more derived struct members, each provided as a full struct member declaration and separated by semicolons in the invocation. Use JUNO_MODULE_EMPTY if there are no derivations.

Note

The first member of the union is always the root, accessible via the alias JUNO_MODULE_SUPER.

JUNO_MODULE_ARG

#define JUNO_MODULE_ARG

(

...

)

__VA_ARGS__

Pass-through argument pack helper for module macros.

JUNO_MODULE_DECLARE

#define JUNO_MODULE_DECLARE

(

NAME_T

)

typedef union NAME_T NAME_T

Forward-declare a Juno module union type.

Parameters

NAME_T

The module union type name.

JUNO_MODULE_DERIVE

#define JUNO_MODULE_DERIVE	(		ROOT_T,
			...
	)

Value:

{ \
    ROOT_T JUNO_MODULE_SUPER; \
    __VA_ARGS__ \
}

Implement a derived module embedding the root as the first member.

Parameters

ROOT_T	The module root type.
...	Implementation-specific members.

Note

The first member is always the embedded root, accessible via JUNO_MODULE_SUPER.

JUNO_MODULE_DERIVE_DECLARE

#define JUNO_MODULE_DERIVE_DECLARE

(

NAME_T

)

JUNO_MODULE_ROOT_DECLARE(NAME_T)

Forward-declare a derived module struct type.

Parameters

NAME_T

The derived struct type name.

JUNO_MODULE_EMPTY

#define JUNO_MODULE_EMPTY

Helper for module definitions with no additional members.

JUNO_MODULE_GET_API

#define JUNO_MODULE_GET_API	(		ptModule,
			ROOT_T
	)		((const ROOT_T *)ptModule)->ptApi

Retrieve the API pointer from a module (via its root view).

Parameters

ptModule	Pointer to the module instance (module union or any derived/root view).
ROOT_T	The root type of the module.

Returns

The const API_T* stored in the root's ptApi field.

Warning

This cast assumes the root is the first member of any derived or union representation, which is guaranteed when using the macros in this header.

JUNO_MODULE_OPTION

#define JUNO_MODULE_OPTION	(		NAME_T,
			SOME_T
	)

Value:

typedef struct NAME_T \
{ \
    bool bIsSome; \
    SOME_T tSome; \
} NAME_T

Define an option type combining a presence flag and a payload.

Parameters

NAME_T	Name of the option struct to define.
SOME_T	Type of the payload when present.

The generated struct has fields:

• bool bIsSome;
• SOME_T tSome;

JUNO_MODULE_RESULT

#define JUNO_MODULE_RESULT	(		NAME_T,
			OK_T
	)

Value:

typedef struct NAME_T \
{ \
    JUNO_STATUS_T tStatus; \
    OK_T tOk; \
} NAME_T

Define a result type combining a status and a success payload.

Parameters

NAME_T	Name of the result struct to define.
OK_T	Type of the success payload contained in the result.

The generated struct has fields:

• JUNO_STATUS_T tStatus;
• OK_T tOk;

JUNO_MODULE_ROOT

#define JUNO_MODULE_ROOT	(		API_T,
			...
	)

Value:

{ \
    const API_T *ptApi; \
    JUNO_FAILURE_HANDLER_T JUNO_FAILURE_HANDLER; \
    JUNO_USER_DATA_T *JUNO_FAILURE_USER_DATA; \
    __VA_ARGS__ \
}

Implement a module root struct containing ptApi and failure fields.

Parameters

API_T	The API (vtable) type for the module.
...	Additional root members (freestanding types recommended).

Note

Expands to a struct body whose first fields are: const API_T *ptApi;, failure handler pointer, and user-data pointer, followed by user-specified members.

JUNO_MODULE_ROOT_DECLARE

#define JUNO_MODULE_ROOT_DECLARE

(

NAME_T

)

typedef struct NAME_T NAME_T

Forward-declare a module root struct type.

Parameters

NAME_T

The root struct type name.

JUNO_MODULE_SUPER

#define JUNO_MODULE_SUPER   tRoot

Standard member name for the embedded module root.

JUNO_NONE_OPTION

#define JUNO_NONE_OPTION

(

default_value

)

{false, default_value}

Construct an option in the empty state, carrying a default payload.

JUNO_OK

#define JUNO_OK

(

result

)

result.tOk

Access the success payload from a result produced by JUNO_MODULE_RESULT.

JUNO_OK_RESULT

#define JUNO_OK_RESULT

(

value

)

{JUNO_STATUS_SUCCESS, value}

Construct a result indicating success with the provided payload.

JUNO_SOME

#define JUNO_SOME

(

result

)

result.tSome

Access the payload from an option produced by JUNO_MODULE_OPTION.

JUNO_SOME_OPTION

#define JUNO_SOME_OPTION

(

value

)

{true, value}

Construct an option in the present state with the provided payload.

JUNO_TRAIT_DERIVE

#define JUNO_TRAIT_DERIVE	(		ROOT_T,
			...
	)		JUNO_MODULE_DERIVE(ROOT_T, __VA_ARGS__)

Alias to define a trait derivation with the standard layout.

JUNO_TRAIT_ROOT

#define JUNO_TRAIT_ROOT	(		API_T,
			...
	)

Value:

{ \
    const API_T *ptApi; \
    __VA_ARGS__ \
}

Define a trait root carrying only the API pointer and members.

Parameters

API_T	The API (vtable) type for the trait.
...	Additional members for the trait root.

Note

Traits omit failure handler fields and only carry the API pointer.