Description

Lumiera interface macros and structures.

Lumiera uses a system of versioned interfaces as external extension points and for defining plug-ins. The interfaces defined here are C compatible and, thus, can be used by any language able to bind to C. The interfaces are versioned to provide forward and backward compatibility for both source and binary deployment of modules.

Overview

To make an interface available to code so that the code can use the interface, the interface needs to be declared and then defined. We provide a number of macros here which ease this process.

The interface is declared by placing the following macro in a header file:

LUMIERA_INTERFACE_DECLARE(name, version,
                          LUMIERA_INTERFACE_SLOT(ret, name, params),
                          ...
                         )

Any code that wants to use this interface must then include the header file.

The interface is defined by mapping interface functions to slots, or providing inline definitions for slot functions. Defining the interface has the following form:

LUMIERA_INTERFACE_INSTANCE(iname, version, name, descriptor, acquire, release,
                           LUMIERA_INTERFACE_MAP (slot, function),
                           LUMIERA_INTERFACE_INLINE (slot, ret, params, {body}),
                           ...
                          )

A collection of interfaces can be defined in 2 different ways depending on where whether the interface is exported by the core, or by a plugin:

LUMIERA_EXPORT(queryfunc,
               LUMIERA_INTERFACE_DEFINE(...),
               ...
               ) // Exporting from the core
 LUMIERA_PLUGIN(descriptor, acquire, release,
                LUMIERA_INTERFACE_DEFINE(...),
                ...
                ) // Exporting from an interface

Naming and Versioning

Interfaces have unique names and a major and minor version. The name and the major version is used to construct a C identifier for the interface, the minor version is implicitly defined by the number of functions in the interface. Interface instances are not versioned by the interface system, versioning these will be defined somewhere else.

Slot names are normal C identifiers, how these shall be versioned has to be defined somewhere else and is not the subject of the interface system. Each function can have its own unique UUID.

Definition in file interface.h.

#include "lib/ppmpl.h"
#include "lib/psplay.h"

Classes
struct	lumiera_interface
	Header for an interface, just the absolute necessary metadata. More...

struct	lumiera_interfaceslot
	This is just a placeholder for an entry in a interface table. More...

Typedefs
typedef lumiera_interface *	LumieraInterface

typedef lumiera_interfaceslot *	LumieraInterfaceslot

Macros
#define	LUMIERA_EXPORT(...)
	Generate interface container suitable for enumerating interfaces. More...

#define	LUMIERA_INTERFACE_CAST(name, version) (LUMIERA_INTERFACE_TYPE(name, version)*)
	Construct a cast to the target interface type Used to cast a generic LumieraInterface to the real type. More...

#define	LUMIERA_INTERFACE_CLOSE(handle) lumiera_interface_close (&(handle)->interface_header_)

#define	LUMIERA_INTERFACE_DECLARE(name, version, ...)
	Declare an interface. More...

#define	LUMIERA_INTERFACE_DNAME(iname, version, dname) PPMPL_CAT (LUMIERA_INTERFACE_INAME (iname, version), _##dname)
	Construct a definition identifier for an interface. More...

#define	LUMIERA_INTERFACE_DSTRING(iname, version, dname) PPMPL_STRINGIFY (LUMIERA_INTERFACE_DNAME (iname, version, dname))
	Construct a definition string for an interface. More...

#define	LUMIERA_INTERFACE_HANDLE(interface, version) LUMIERA_INTERFACE_TYPE(interface, version)*
	create a handle for a interface (WIP)

#define	LUMIERA_INTERFACE_INAME(name, version) name##_##version
	Construct a type identifier for an interface. More...

#define	LUMIERA_INTERFACE_INLINE_NAME(slot) PPMPL_CAT(lumiera_##slot##_l, __LINE__)

#define	LUMIERA_INTERFACE_INSTANCE(iname, version, name, descriptor, acquire, release, ...)
	Define an interface instance. More...

#define	LUMIERA_INTERFACE_OPEN(interface, version, minminor, name) LUMIERA_INTERFACE_CAST(interface, version) lumiera_interface_open (#interface, version, minminor, #name)

#define	LUMIERA_INTERFACE_REF(iname, version, dname) (LumieraInterface)&LUMIERA_INTERFACE_DNAME(iname, version, dname)
	Return a reference (pointer) to an interface implementation. More...

#define	LUMIERA_INTERFACE_REGISTEREXPORTED lumiera_interfaceregistry_bulkregister_interfaces (lumiera_plugin_interfaces(), NULL)
	Register all exported interfaces when not a plugin This is a no-op when LUMIERA_PLUGIN is defined, since plugins are automatically registered.

#define	LUMIERA_INTERFACE_TYPE(name, version) struct LUMIERA_INTERFACE_INAME(name, version)
	Construct the type of the interface. More...

#define	LUMIERA_INTERFACE_UNREGISTEREXPORTED lumiera_interfaceregistry_bulkremove_interfaces (lumiera_plugin_interfaces())
	Unregister all exported interfaces when not a plugin This is a no-op when LUMIERA_PLUGIN is defined, since plugins are automatically registered.

#define	LUMIERA_PLUGIN_INTERFACEHANDLE static LUMIERA_INTERFACE_HANDLE(lumieraorg_interface, 0) lumiera_interface_handle
	Create a plugin interface when being compiled as plugin.

#define	LUMIERA_PLUGIN_STORE_INTERFACEHANDLE(name) lumiera_interface_handle = LUMIERA_INTERFACE_CAST (lumieraorg_interface, 0) name

#define	LUMIERA_PLUGININTERFACE

#define	PPMPL_FOREACH_L1_P1_LUMIERA_INTERFACE_DEFINE(iname, version, name, descriptor, acquire, release, ...)

#define	PPMPL_FOREACH_L1_P2_LUMIERA_INTERFACE_DEFINE(iname, version, name, descriptor, acquire, release, ...) &LUMIERA_INTERFACE_DNAME(iname, version, name).interface_header_,

#define	PPMPL_FOREACH_LUMIERA_INTERFACE_SLOT(ret, name, params) ret (*name) params; \
	Declare a function slot inside an interface. More...

#define	PPMPL_FOREACH_P1_LUMIERA_INTERFACE_INLINE(slot, ret, params, ...)
	Map a inline defined function to a interface slot. More...

#define	PPMPL_FOREACH_P1_LUMIERA_INTERFACE_MAP(slot, function)
	Map a function to a interface slot. More...

#define	PPMPL_FOREACH_P2_LUMIERA_INTERFACE_INLINE(slot, ret, params, ...) LUMIERA_INTERFACE_INLINE_NAME(slot),\

#define	PPMPL_FOREACH_P2_LUMIERA_INTERFACE_MAP(slot, function) function,\

Functions
void	lumiera_interface_close (LumieraInterface self)
	Close an interface after use. More...

	LUMIERA_INTERFACE_DECLARE (lumieraorg_interface, 0, LUMIERA_INTERFACE_SLOT(LumieraInterface, open,(const char interface, unsigned version, size_t minminorversion, const char name)), LUMIERA_INTERFACE_SLOT(void, close,(LumieraInterface self)), LUMIERA_INTERFACE_SLOT(unsigned, version,(LumieraInterface self, const char *iname)),)
	Define an interface for the above.

	LUMIERA_INTERFACE_DECLARE (lumieraorg__plugin, 0, LUMIERA_INTERFACE_SLOT(LumieraInterface *, plugin_interfaces,(void)),)
	Plugin interface.

void	lumiera_interface_destroy (void)
	deregistering implementations of the above interface

void	lumiera_interface_init (void)
	registering implementations of the above interface

LumieraInterface	lumiera_interface_open (const char interface, unsigned version, size_t minminorversion, const char name)
	Open an interface by version and name. More...

unsigned	lumiera_interface_version (LumieraInterface self, const char *iname)
	Runtime check for interface type and version. More...

Macro Definition Documentation

◆ LUMIERA_INTERFACE_INAME

#define LUMIERA_INTERFACE_INAME	(	name,
		version
	)	name##_##version

Construct a type identifier for an interface.

Parameters

name	name of the interface
version	major version of this interface

Definition at line 102 of file interface.h.

◆ LUMIERA_INTERFACE_DNAME

#define LUMIERA_INTERFACE_DNAME	(	iname,
		version,
		dname
	)	PPMPL_CAT (LUMIERA_INTERFACE_INAME (iname, version), _##dname)

Construct a definition identifier for an interface.

Parameters

iname	name of the interface
version	major version of the interface
dname	name for the instance

Returns: constructed identifier

Definition at line 111 of file interface.h.

◆ LUMIERA_INTERFACE_DSTRING

#define LUMIERA_INTERFACE_DSTRING	(	iname,
		version,
		dname
	)	PPMPL_STRINGIFY (LUMIERA_INTERFACE_DNAME (iname, version, dname))

Construct a definition string for an interface.

Parameters

iname	name of the interface
version	major version of the interface
dname	name for the instance

Returns: constructed string

Definition at line 120 of file interface.h.

◆ LUMIERA_INTERFACE_REF

#define LUMIERA_INTERFACE_REF	(	iname,
		version,
		dname
	)	(LumieraInterface)&LUMIERA_INTERFACE_DNAME(iname, version, dname)

Return a reference (pointer) to an interface implementation.

Parameters

iname	name of the interface
version	major version of the interface
dname	name for the instance

Definition at line 128 of file interface.h.

Referenced by NotificationService::NotificationService(), and SessionCommandService::SessionCommandService().

◆ LUMIERA_INTERFACE_TYPE

#define LUMIERA_INTERFACE_TYPE	(	name,
		version
	)	struct LUMIERA_INTERFACE_INAME(name, version)

Construct the type of the interface.

Parameters

name	name of the interface
version	major version of this interface

Definition at line 137 of file interface.h.

◆ LUMIERA_INTERFACE_CAST

#define LUMIERA_INTERFACE_CAST	(	name,
		version
	)	(LUMIERA_INTERFACE_TYPE(name, version)*)

Construct a cast to the target interface type Used to cast a generic LumieraInterface to the real type.

Parameters

name	name of the interface
version	major version of this interface

Definition at line 146 of file interface.h.

◆ LUMIERA_INTERFACE_DECLARE

#define LUMIERA_INTERFACE_DECLARE	(	name,
		version,
		...
	)

Value:

LUMIERA_INTERFACE_TYPE(name, version)                   \
{                                                       \
  lumiera_interface interface_header_;                  \
  PPMPL_FOREACH(_, __VA_ARGS__)                         \
}

Declare an interface.

Parameters

name	name of the interface
version	major version of this interface declaration. 0 denotes an experimental interface, otherwise this will begin at 1 onwards for each new (incompatible) change to an interface. The older interface declarations may still be maintained in parallel (backwards compatibility!).
...	Slot declarations for the functions provided by this interface

See also: LUMIERA_INTERFACE_SLOT The number of Slots in an interface defines its 'minor' version. New slots must be added at the end. The prototype and order of existing slots must not be changed. Slots may be renamed, for example a slot 'foo' can be renamed to 'foo_old' when a new 'foo' slot is added. Binary modules will then still use the 'foo_old' slot which was the 'foo' slot at the compile time while compiling modules from source will use the new 'foo' slot. This may be intentionally used to break compilation and force the update of modules to a new api.

Definition at line 163 of file interface.h.

◆ PPMPL_FOREACH_LUMIERA_INTERFACE_SLOT

#define PPMPL_FOREACH_LUMIERA_INTERFACE_SLOT	(	ret,
		name,
		params
	)	ret (*name) params; \

Declare a function slot inside an interface.

Parameters

ret	return type of the function
name	name of this slot
params	parenthesised list of parameters for the function

Definition at line 176 of file interface.h.

◆ LUMIERA_INTERFACE_INSTANCE

#define LUMIERA_INTERFACE_INSTANCE	(	iname,
		version,
		name,
		descriptor,
		acquire,
		release,
		...
	)

Value:

PPMPL_FOREACH(_P1_, __VA_ARGS__)                                                                \
LUMIERA_INTERFACE_TYPE(iname, version) LUMIERA_INTERFACE_DNAME(iname, version, name) =          \
{                                                                                               \
{                                                                                               \
  #iname,                                                                                       \
  version,                                                                                      \
  #name,                                                                                        \
  sizeof (LUMIERA_INTERFACE_TYPE(iname, version)),                                              \
  descriptor,                                                                                   \
  acquire,                                                                                      \
  release                                                                                       \
},                                                                                              \
PPMPL_FOREACH(_P2_, __VA_ARGS__)                                                                \
}

Define an interface instance.

Parameters

iname	name of the interface to instance
version	major version of the interface to instance
name	name of the instance
descriptor	pointer to an interface instance which provides a description of this interface, might be NULL
acquire	a function which is called whenever this interface is opened for using, might be NULL
release	a function which is called whenever this interface is closed after use, might be NULL
...	map functions to interface slots

See also: LUMIERA_INTERFACE_MAP

Definition at line 194 of file interface.h.

◆ PPMPL_FOREACH_P1_LUMIERA_INTERFACE_MAP

#define PPMPL_FOREACH_P1_LUMIERA_INTERFACE_MAP	(	slot,
		function
	)

Map a function to a interface slot.

Parameters

slot	name of the slot to be mapped
function	name of the function to be mapped on slot

Note: C++ requires that all mappings are in the same order than defined in the interface declaration, this would be good style for C too anyways

Definition at line 219 of file interface.h.

◆ PPMPL_FOREACH_P1_LUMIERA_INTERFACE_INLINE

#define PPMPL_FOREACH_P1_LUMIERA_INTERFACE_INLINE	(	slot,
		ret,
		params,
		...
	)

Value:

static ret                                                                    \
  LUMIERA_INTERFACE_INLINE_NAME(slot) params                                    \
  __VA_ARGS__

Map a inline defined function to a interface slot.

Parameters

slot	name of the slot to be mapped
ret	return type of the inline function
params	parenthesised list of parameters given to the function
...	braced function body

Note: C++ requires that all mappings are in the same order than defined in the interface declaration, this would be good style for C too anyways

Definition at line 241 of file interface.h.

◆ PPMPL_FOREACH_L1_P1_LUMIERA_INTERFACE_DEFINE

#define PPMPL_FOREACH_L1_P1_LUMIERA_INTERFACE_DEFINE	(	iname,
		version,
		name,
		descriptor,
		acquire,
		release,
		...
	)

Value:

LUMIERA_INTERFACE_INSTANCE (iname, version,                                                                     \
                            name,                                                                               \
                            descriptor,                                                                         \
                            acquire,                                                                            \
                            release,                                                                            \
                            __VA_ARGS__                                                                         \
                            );

Definition at line 259 of file interface.h.

◆ LUMIERA_EXPORT

#define LUMIERA_EXPORT ( ... )

Value:

PPMPL_FOREACH_L1(_P1_, __VA_ARGS__)             \
static LumieraInterface*                        \
lumiera_plugin_interfaces (void)                \
{                                               \
 static LumieraInterface interfaces[] =         \
  {                                             \
    PPMPL_FOREACH_L1(_P2_, __VA_ARGS__)         \
    NULL                                        \
  };                                            \
  return interfaces;                            \
}                                               \
LUMIERA_PLUGININTERFACE

Generate interface container suitable for enumerating interfaces.

This takes a list of interface definitions, instantiates them and places pointers to them into a zero terminated array which address is returned by a static function named 'lumiera_plugin_interfaces'. For interfaces generated by he core, the user is responsible to register these dynamically. When LUMIERA_PLUGIN is defined, things change and an additional 'lumieraorg__plugin' interface is generated. The plugin loader then uses this to register the provided interfaces automatically.

Parameters

...	list of LUMIERA_INTERFACE_DEFINE()/LUMIERA_INTERFACE_INLINE() for all interfaces this plugin provides.

Definition at line 282 of file interface.h.

Function Documentation

◆ lumiera_interface_open()

LumieraInterface lumiera_interface_open	(	const char *	interface,
		unsigned	version,
		size_t	minminorversion,
		const char *	name
	)

Open an interface by version and name.

Looks up the requested interface, possibly loading it from a plugin.

Parameters

interface	name of the interface definition
version	major version of the interface definition
minminorversion	required minor version (structure size)
name	name of the interface implementation

Returns: the queried interface handle on success, else NULL

Definition at line 58 of file interface.c.

◆ lumiera_interface_close()

void lumiera_interface_close ( LumieraInterface self )

Close an interface after use.

Parameters

self	interface to be closed consider 'self' to be invalidated after this call

Definition at line 235 of file interface.c.

References LUMIERA_RECMUTEX_SECTION.

Referenced by lumiera_interface_destroy().

Here is the caller graph for this function:

◆ lumiera_interface_version()

unsigned lumiera_interface_version	(	LumieraInterface	self,
		const char *	iname
	)

Runtime check for interface type and version.

Parameters

self	interface to check
iname	name of the interface

Returns: version of the interface or ~0 (-1) if iname doesn't match the requested name

Definition at line 247 of file interface.c.

Description

Overview

Naming and Versioning

Classes

Typedefs

Macros

Functions

Macro Definition Documentation

◆ LUMIERA_INTERFACE_INAME

◆ LUMIERA_INTERFACE_DNAME

◆ LUMIERA_INTERFACE_DSTRING

◆ LUMIERA_INTERFACE_REF

◆ LUMIERA_INTERFACE_TYPE

◆ LUMIERA_INTERFACE_CAST

◆ LUMIERA_INTERFACE_DECLARE

◆ PPMPL_FOREACH_LUMIERA_INTERFACE_SLOT

◆ LUMIERA_INTERFACE_INSTANCE

◆ PPMPL_FOREACH_P1_LUMIERA_INTERFACE_MAP

◆ PPMPL_FOREACH_P1_LUMIERA_INTERFACE_INLINE

◆ PPMPL_FOREACH_L1_P1_LUMIERA_INTERFACE_DEFINE

◆ LUMIERA_EXPORT

Function Documentation

◆ lumiera_interface_open()

◆ lumiera_interface_close()

◆ lumiera_interface_version()