MkRuntimeC_Interface_C_API

MkRuntimeC - The MkRuntimeRLS, a thread-local storage for application-global data … More...

Collaboration diagram for MkRuntimeC_Interface_C_API:

Classes
struct	libmkkernel::MkRuntimeCallbackS
	keep callback related data … More...

Macros
#define	MK_RT_ATTR_HDL_CHECK(x)
#define	MK_RT_ATTR_CHECK_RUNTIME_NULL   MkRtSetup_NULL_RT
#define	MK_RT_ATTR_CHECK_RUNTIME_XN(x)
#define	MK_RT_ATTR_CHECK_RUNTIME_ON(x)
#define	MK_RT_ATTR_CHECK_RUNTIME_O(x)
#define	MK_RT_ATTR_NONNULL_1_CHECK(x)
#define	MK_RT_ATTR_NONNULL_2_CHECK(x)

Typedefs
typedef void(*	libmkkernel::MkRuntimeInitF) (struct MkRuntimeS *mkRt)
	additional runtime initialization function …

Functions
MK_EXTERN MK_RT	libmkkernel::MkRuntimeInit (MK_RT const mkrt)
	initialize MkRuntimeRLS …
MK_RT	libmkkernel::MkRuntimeGet (void)
	return a initialized MkRuntimeRLS …

Variables
MK_EXTERN_DATA MkThreadLocal struct MkRuntimeS	libmkkernel::MkRuntimeRLS
	RLS …

MkRuntimeCallback
Register callback used to setup library-local runtime attributes … Sometimes the features provided by MkRuntimeRLS are not fullfilling the requirements of the implementation. Sometimes the functions provided by the MkRuntimeRLS do not meet the implementation requirements. Two methods are offered to retrofit the missing capability: Add a MkRuntimeRLS-callback that is called whenever a new MkRuntimeRLS is created. (simply) Adding a MkRuntimeRLS extension that creates an additional MkRuntimeRLS parallel to the initial MkRuntimeRLS (complicated). Example from "LibLcConfig_jv.c": add a runtime-callback to implement a specific type. // LC classes MkThreadLocal MK_TYP LcConfigC_TT = NULL; MkThreadLocal MK_TYP LcSettingC_TT = NULL; ... static struct MkRuntimeCallbackS sLcRuntimeCallback = {0}; ... static void sConfigRuntimeCallback ( struct MkRuntimeS * mkrt ) { LcConfigC_TT = MkTypeCreate(LcConfigC, MkObjectC, "LcConfigC"); LcConfigC_TT->constructor = pConfigCreate; LcConfigC_TT->destructor = pConfigDelete; LcSettingC_TT = MkTypeCreate(LcSettingC, MkObjectC, "LcSettingC"); LcSettingC_TT->constructor = pSettingCreate; LcSettingC_TT->destructor = pSettingDelete; if (LcSetupThread) { (*LcSetupThread)(MK_RT_CALL_ONLY); } } ... void LcSetup(void) { ... sLcRuntimeCallback.mkrt = mkrt; sLcRuntimeCallback.cb = NS(sLcRuntimeCallback); // class specific initialization MkRuntimeCallbackAdd( &sLcRuntimeCallback ); ... }
MK_EXTERN void	libmkkernel::MkRuntimeCallbackAdd (struct MkRuntimeCallbackS *cbdata, MK_RT mkrt, MkRuntimeInitF rt_callback, MK_STRN ident)
	add a callback to the runtime …
MK_EXTERN void	libmkkernel::MkRuntimeCallbackDel (struct MkRuntimeCallbackS *cbdata)
	delete a callback from the runtime …

META_HAS_THREAD
#define	MkThreadLocal   __thread
#define	MK_RT_IS_ARG   1
#define	MK_RT_ARGS_ONLY   MK_RT mkrt
#define	MK_RT_ARGS   MK_RT_ARGS_ONLY,
#define	MK_RT_CALL_ONLY   mkrt
#define	MK_RT_CALL   MK_RT_CALL_ONLY,
#define	MK_RT_CALL_O(o)
#define	MK_RT_CALL_X(x)
#define	MK_RT_CALL_NULL_ONLY   MkRT
#define	MK_RT_CALL_NULL   MK_RT_CALL_NULL_ONLY,
#define	MK_RT_NULL   NULL,
#define	MK_RT_PTR   mkrt
#define	MK_RT_REF   (*mkrt)
#define	MK_RT_REF_NULL   (MkRuntimeRLS)
#define	MK_RT_UNUSED   MK_UNUSED
#define	MK_RT_CALL_RT(ptr)
#define	MK_RT_PARSER_ONLY   MK_RT_ARGS_ONLY __parser__(internal,default=N#RUNTIME)
#define	MK_RT_PARSER   MK_RT_PARSER_ONLY,
#define	MK_RT_ATTR_FORMAT_1   __attribute__((format (printf, 2, 3)))
#define	MK_RT_ATTR_FORMAT_2   __attribute__((format (printf, 3, 4)))
#define	MK_RT_ATTR_FORMAT_4   __attribute__((format (printf, 5, 6)))
#define	MK_RT_ATTR_RUNTIME
#define	MK_RT_ATTR_NONNULL_1
#define	MK_RT_ATTR_NONNULL_2
#define	MK_RT_ATTR_HDL
#define	MK_RT_ATTR_HDL

MkRtSetup
#define	MkRT   (&MkRuntimeRLS)
#define	MkRT_R   (MkRuntimeRLS)
#define	MkRT_O(o)
#define	MkRT_X(x)
#define	MkRT_ONN(o)
#define	MkRT_ON(o)
#define	MkRT_XN(x)
#define	MkRtSetup_O(o)
#define	MkRtSetup_X(x)
#define	MkRtSetup_XN(x)
#define	MkRtSetup_ON(o)
#define	MkRtSetup_NULL   MK_RT_UNUSED MK_RT const mkrt = MkRuntimeGet();
#define	MkRtSetup_RT(r)
#define	MkRtSetupFromRtExt(rtx)
#define	MkRtSetup_O_RT(o)
#define	MkRtSetup_X_RT(x)
#define	MkRtSetup_XN_RT(x)
#define	MkRtSetup_ON_RT(o)
#define	MkRtSetup_NULL_RT   if (mkrt == NULL) mkrt = MkRT

Detailed Description

MkRuntimeC - The MkRuntimeRLS, a thread-local storage for application-global data …

‍The goal of the runtime-interface is to provide the best performance for thread and non-thread.

on thread

the cache-access with the MkRuntimeRLS-pointer is used.

• The ccmkkernel was build with configure --enable-threads ....
• The application has multiple threads and every PLMK (Programming-Language-Micro-Kernel)-thread has his own MkRuntimeRLS.
• The MkRuntimeRLS itself is created as T)hread-L)ocal-S)torage (TLS).
• The MkRuntimeRLS can be reached via the macro MkRT (slow) or via the MkRuntimeRLS-cache (fast),
• The MkRT is resolving with a tls-resolution-call, using multiple MkRT creates multiple tls-resolution-calls (very slow).
• The runtime-cache is added only once to the function-body and is later reused for every MkRuntimeRLS-access (fast).
• The runtime-cache is added via first-argument (fast) or via a MkRuntimeRLS-object-resolution (also fast, but slower than first-argument) or via MkRT if no first-argument or MkRuntimeRLS-object-resolution is available (slow)
• The MkRuntimeRLS-object-resolution get the MkRuntimeRLS from the libmkkernel::MkObjectS::objRt attribute.

on non-thread

the direct-access with the MkRuntimeRLS-reference is used.

• The ccmkkernel was build with configure --disable-threads ....
• The application has only one therad and only one MkRuntimeRLS.
• The MkRuntimeRLS is created as A)pplication-G)lobal-S)torage (AGS).
• The MkRuntimeRLS can be reached via the macro MkRT, compile-time-resolving with a direct-access (fast)

thread and non-thread

The diffrence between thread and non-thread is hidden behind the MK_RT_*, MkRt* or MkRT* macros.

Characteristics of the runtime:

• The MkRuntimeRLS is defined as: MkThreadLocal struct MkRuntimeS MkRuntimeRLS = {0};.
• The macro MkRT will always resolve to (&MkRuntimeRLS)
• The MkThreadLocal will expand to __thread with thread-support and otherwise to empty.
• There will be exact one MkRuntimeRLS per PLMK (Programming-Language-Micro-Kernel)-thread.
• In a non-threaded-environment only one MkRuntimeRLS exists.
• The new MkRuntimeRLS is initialized with the fist MkRtSetup_xxx call after the thread-creation.

threaded versa non-threaded:

The internal MkRuntimeRLS access is different for thread and non-thread.

‍Always use the MK_RT_xxx and MkRtSetup_xxx macros to get best performane to access the MkRuntimeRLS. Summary: Internal access to the MkRuntimeRLS

threaded	storage	resolve	access	MkRtSetup_xxx	speed
yes	thread-local-storage	run-time	cache	via mkrt	fast enough but slower than non-thread
no	application-global-storage	compile-time	direct	via MkRT	fast

Create the local-cache:

The local-cache is only required for a threaded-environment and is defined internal as mkrt variable initialized with a pointer to the MkRuntimeRLS.

‍do NOT use the mkrt direct because your code will NOT compile in a non-thread environment.

In a runtime-aware function the local-cache is always as first argument in the function.

void myfunc( MK_RT_ARGS arg1, arg2, argX... ) {
  ...
}

In a non-runtime-aware method the local-cache is created using the instance-argument:

void myfunc( instance, arg2, argX... ) {
  MkRtSetup_X(instance)
  ...
}

In a non-runtime-aware static-function the local-cache is created using TLS direct:

void myfunc( instance, arg2, argX... ) {
  MkRtSetup_NULL
  ...
}

In a non-runtime-aware static-function with instance-argument the local-cache is created using instArg:

void myfunc( arg1, instArg, argX... ) {
  MkRtSetup_X(instArg)
  ...
}

Summary: In a non-runtime-aware function use the instance to setup the cache-access otherwise MkRtSetup_NULL:

source	local-cache is created with	example	speed
instance	MkRtSetup_O , MkRtSetup_X	MkRtSetup_X(instance)	fast
runtime	MkRtSetup_NULL	MkRtSetup_NULL	slow in non-static

Access to the runtime:

Do not use mkrt directly because mkrt will disappear in a non-threaded-environment.

access as	macro	threaded	nothreaded	example	speed
reference	MK_RT_REF	(*mkrt)	MkRuntimeRLS	MK_RT_REF.debug	fast if static
pointer	MK_RT_PTR	mkrt	(&MkRuntimeRLS)	MK_RT_PTR->debug	slow

Always try to use the MK_RT_REF for best performance in a threaded and non-threaded-environment.

Define and Call a runtime-aware function:

It is a difference if a runtime-aware function is called with or without argument.

args	function definition	function parser extension	function call
multiple args	MK_RT_ARGS	MK_RT_PARSER	MK_RT_CALL
no args	MK_RT_ARGS_ONLY	MK_RT_PARSER_ONLY	MK_RT_CALL_ONLY

Between the MK_RT_ARGS... and MK_RT_CALL... and the first argument is no comma.

Example: a runtime-aware function

void myfunc (MK_RT_ARGS int arg1, int arg2, ...) {}
  ...
  MK_RT_REF.debug = someValue;    // define MK_RT_REF from MK_RT_ARGS (fast)
  ...
}

Example: call a runtime-aware function

myfunc ( MK_RT_CALL 1 , 2 , ... );

Example: setup of the runtime in a non-runtime-aware function with instance argument

void myfunc (MK_BUF mybuf, MK_I32 someValue) {
  MkRtSetup_X(mybuf);             // define MK_RT_REF local using `MkOBJ_R(mybuf).objRt` (fast)
  ...
  MK_RT_REF.debug = someValue;    // use the local-cache as reference to access the MkRuntimeRLS
  ...
}

Note

All functions and macros used are related to the namespace of the library:

• The namespace from libmkkernel is mk,Mk,MK
• The namespace from libmqmsgque is mq,Mq,MQ
• The namespace from liblcconfig is lc,Lc,LC
• The namespace from libsq3lite is sq3,Sq3,SQ3
• ...

See also

MkRuntimeC DETAIL

Macro Definition Documentation

MK_RT_ARGS

#define MK_RT_ARGS   MK_RT_ARGS_ONLY,

Definition at line 775 of file LibMkKernel_mk.h.

MK_RT_ARGS_ONLY

#define MK_RT_ARGS_ONLY   MK_RT mkrt

Definition at line 774 of file LibMkKernel_mk.h.

MK_RT_ATTR_CHECK_RUNTIME_NULL

#define MK_RT_ATTR_CHECK_RUNTIME_NULL   MkRtSetup_NULL_RT

Definition at line 852 of file LibMkKernel_mk.h.

MK_RT_ATTR_CHECK_RUNTIME_O

#define MK_RT_ATTR_CHECK_RUNTIME_O

(

x

)

Value:

MkRtSetup_O_RT(x)

Definition at line 855 of file LibMkKernel_mk.h.

MK_RT_ATTR_CHECK_RUNTIME_ON

#define MK_RT_ATTR_CHECK_RUNTIME_ON

(

x

)

Value:

MkRtSetup_ON_RT(x)

Definition at line 854 of file LibMkKernel_mk.h.

MK_RT_ATTR_CHECK_RUNTIME_XN

#define MK_RT_ATTR_CHECK_RUNTIME_XN

(

x

)

Value:

MkRtSetup_XN_RT(x)

Definition at line 853 of file LibMkKernel_mk.h.

MK_RT_ATTR_FORMAT_1

#define MK_RT_ATTR_FORMAT_1   __attribute__((format (printf, 2, 3)))

Definition at line 790 of file LibMkKernel_mk.h.

MK_RT_ATTR_FORMAT_2

#define MK_RT_ATTR_FORMAT_2   __attribute__((format (printf, 3, 4)))

Definition at line 791 of file LibMkKernel_mk.h.

MK_RT_ATTR_FORMAT_4

#define MK_RT_ATTR_FORMAT_4   __attribute__((format (printf, 5, 6)))

Definition at line 792 of file LibMkKernel_mk.h.

MK_RT_ATTR_HDL [1/2]

#define MK_RT_ATTR_HDL

Definition at line 803 of file LibMkKernel_mk.h.

MK_RT_ATTR_HDL [2/2]

#define MK_RT_ATTR_HDL

Definition at line 803 of file LibMkKernel_mk.h.

MK_RT_ATTR_HDL_CHECK

#define MK_RT_ATTR_HDL_CHECK

(

x

)

Value:

assert(x!=NULL)

Definition at line 849 of file LibMkKernel_mk.h.

MK_RT_ATTR_NONNULL_1

#define MK_RT_ATTR_NONNULL_1

Definition at line 801 of file LibMkKernel_mk.h.

MK_RT_ATTR_NONNULL_1_CHECK

#define MK_RT_ATTR_NONNULL_1_CHECK

(

x

)

Value:

assert(x!=NULL)

Definition at line 856 of file LibMkKernel_mk.h.

MK_RT_ATTR_NONNULL_2

#define MK_RT_ATTR_NONNULL_2

Definition at line 802 of file LibMkKernel_mk.h.

MK_RT_ATTR_NONNULL_2_CHECK

#define MK_RT_ATTR_NONNULL_2_CHECK

(

x

)

Value:

assert(x!=NULL)

Definition at line 857 of file LibMkKernel_mk.h.

MK_RT_ATTR_RUNTIME

#define MK_RT_ATTR_RUNTIME

Definition at line 795 of file LibMkKernel_mk.h.

MK_RT_CALL

#define MK_RT_CALL   MK_RT_CALL_ONLY,

Definition at line 777 of file LibMkKernel_mk.h.

MK_RT_CALL_NULL

#define MK_RT_CALL_NULL   MK_RT_CALL_NULL_ONLY,

Definition at line 781 of file LibMkKernel_mk.h.

MK_RT_CALL_NULL_ONLY

#define MK_RT_CALL_NULL_ONLY   MkRT

Definition at line 780 of file LibMkKernel_mk.h.

MK_RT_CALL_O

#define MK_RT_CALL_O

(

o

)

Value:

MkRT_O(o),

Definition at line 778 of file LibMkKernel_mk.h.

MK_RT_CALL_ONLY

#define MK_RT_CALL_ONLY   mkrt

Definition at line 776 of file LibMkKernel_mk.h.

MK_RT_CALL_RT

#define MK_RT_CALL_RT

(

ptr

)

Value:

ptr,

Definition at line 787 of file LibMkKernel_mk.h.

MK_RT_CALL_X

#define MK_RT_CALL_X

(

x

)

Value:

MkRT_X(x),

Definition at line 779 of file LibMkKernel_mk.h.

MK_RT_IS_ARG

#define MK_RT_IS_ARG   1

Definition at line 773 of file LibMkKernel_mk.h.

MK_RT_NULL

#define MK_RT_NULL   NULL,

Definition at line 782 of file LibMkKernel_mk.h.

MK_RT_PARSER

#define MK_RT_PARSER   MK_RT_PARSER_ONLY,

Definition at line 789 of file LibMkKernel_mk.h.

MK_RT_PARSER_ONLY

#define MK_RT_PARSER_ONLY   MK_RT_ARGS_ONLY __parser__(internal,default=N#RUNTIME)

Definition at line 788 of file LibMkKernel_mk.h.

MK_RT_PTR

#define MK_RT_PTR   mkrt

Definition at line 783 of file LibMkKernel_mk.h.

MK_RT_REF

#define MK_RT_REF   (*mkrt)

Definition at line 784 of file LibMkKernel_mk.h.

MK_RT_REF_NULL

#define MK_RT_REF_NULL   (MkRuntimeRLS)

Definition at line 785 of file LibMkKernel_mk.h.

MK_RT_UNUSED

#define MK_RT_UNUSED   MK_UNUSED

Definition at line 786 of file LibMkKernel_mk.h.

MkRT

#define MkRT   (&MkRuntimeRLS)

Definition at line 11575 of file LibMkKernel_mk.h.

MkRT_O

#define MkRT_O

(

o

)

Value:

((o) && (*o).objRt       ? (*o).objRt       : MkRuntimeGet())

Definition at line 11579 of file LibMkKernel_mk.h.

MkRT_ON

#define MkRT_ON

(

o

)

Value:

(       (*o).objRt       ? (*o).objRt       : MkRuntimeGet())

Definition at line 11582 of file LibMkKernel_mk.h.

MkRT_ONN

#define MkRT_ONN

(

o

)

Value:

((*o).objRt)

Definition at line 11581 of file LibMkKernel_mk.h.

MkRT_R

#define MkRT_R   (MkRuntimeRLS)

Definition at line 11576 of file LibMkKernel_mk.h.

MkRT_X

#define MkRT_X

(

x

)

Value:

((x) && MkOBJ_R(x).objRt ? MkOBJ_R(x).objRt : MkRuntimeGet())

Definition at line 11580 of file LibMkKernel_mk.h.

MkRT_XN

#define MkRT_XN

(

x

)

Value:

(       MkOBJ_R(x).objRt ? MkOBJ_R(x).objRt : MkRuntimeGet())

Definition at line 11583 of file LibMkKernel_mk.h.

MkRtSetup_NULL

#define MkRtSetup_NULL   MK_RT_UNUSED MK_RT const mkrt = MkRuntimeGet();

Definition at line 11597 of file LibMkKernel_mk.h.

MkRtSetup_NULL_RT

#define MkRtSetup_NULL_RT   if (mkrt == NULL) mkrt = MkRT

Definition at line 11606 of file LibMkKernel_mk.h.

MkRtSetup_O

#define MkRtSetup_O

(

o

)

Value:

MK_RT_UNUSED MK_RT const mkrt = MkRT_O(o)

Definition at line 11593 of file LibMkKernel_mk.h.

MkRtSetup_O_RT

#define MkRtSetup_O_RT

(

o

)

Value:

if (mkrt == NULL) mkrt = MkRT_O(o)

Definition at line 11602 of file LibMkKernel_mk.h.

MkRtSetup_ON

#define MkRtSetup_ON

(

o

)

Value:

MK_RT_UNUSED MK_RT const mkrt = MkRT_ON(o)

Definition at line 11596 of file LibMkKernel_mk.h.

MkRtSetup_ON_RT

#define MkRtSetup_ON_RT

(

o

)

Value:

if (mkrt == NULL) mkrt = MkRT_ON(o)

Definition at line 11605 of file LibMkKernel_mk.h.

MkRtSetup_RT

#define MkRtSetup_RT

(

r

)

Value:

MK_RT_UNUSED MK_RT const mkrt = r;

Definition at line 11598 of file LibMkKernel_mk.h.

MkRtSetup_X

#define MkRtSetup_X

(

x

)

Value:

MK_RT_UNUSED MK_RT const mkrt = MkRT_X(x)

Definition at line 11594 of file LibMkKernel_mk.h.

MkRtSetup_X_RT

#define MkRtSetup_X_RT

(

x

)

Value:

if (mkrt == NULL) mkrt = MkRT_X(x)

Definition at line 11603 of file LibMkKernel_mk.h.

MkRtSetup_XN

#define MkRtSetup_XN

(

x

)

Value:

MK_RT_UNUSED MK_RT const mkrt = MkRT_XN(x)

Definition at line 11595 of file LibMkKernel_mk.h.

MkRtSetup_XN_RT

#define MkRtSetup_XN_RT

(

x

)

Value:

if (mkrt == NULL) mkrt = MkRT_XN(x)

Definition at line 11604 of file LibMkKernel_mk.h.

MkRtSetupFromRtExt

#define MkRtSetupFromRtExt

(

rtx

)

Value:

MK_RT_UNUSED MK_RT const mkrt = MkRTEXT_R(rtx).mkrthead;

Definition at line 11599 of file LibMkKernel_mk.h.

MkThreadLocal

#define MkThreadLocal   __thread

Definition at line 772 of file LibMkKernel_mk.h.

Typedef Documentation

MkRuntimeInitF

typedef void( * libmkkernel::MkRuntimeInitF) (struct MkRuntimeS *mkRt)

additional runtime initialization function …

Every thread get a thread-specifig runtime and this runtime can be initialized with this function.

See also

libmkkernel::MkRuntimeCallbackAdd libmkkernel::MkRuntimeCallbackDel

Definition at line 11629 of file LibMkKernel_mk.h.

Function Documentation

MkRuntimeCallbackAdd()

MK_EXTERN void libmkkernel::MkRuntimeCallbackAdd	(	struct MkRuntimeCallbackS *	cbdata,
		MK_RT	mkrt,
		MkRuntimeInitF	rt_callback,
		MK_STRN	ident )

add a callback to the runtime …

The callback is used to initialize local runtime-attributes per thread. This initialization is used to do the following tasks:

1. add a library specific new type.
2. add a slot to an already existing type, example: MkTypeS::selfCreate and MkTypeS::selfDelete.

Every type is "thread-local" because every type has the type-(thread)-local memory-allocator located at MkTypeS::objalloc→MkAllocDefS::alloc_data and the type-local alloc-callbacks :

• MkTypeS::objalloc→MkAllocDefS::alloc_createF,
• MkTypeS::objalloc→MkAllocDefS::alloc_deleteF.

The memory-allocator is thread-local because the cache is thread-local including the predefined objects.

Note

Without a thread-local type and a thread-local memory-allocater every access to the memory-allocator (including the cache) have to be protected by a semaphore.

read more at MkTypeCreate

See also

MkRuntimeCallbackDel

MkRuntimeCallbackDel()

MK_EXTERN void libmkkernel::MkRuntimeCallbackDel

(

struct MkRuntimeCallbackS *

cbdata

)

delete a callback from the runtime …

See also

MkRuntimeCallbackAdd

MkRuntimeGet()

MK_RT libmkkernel::MkRuntimeGet ( void )

inline

return a initialized MkRuntimeRLS …

Definition at line 11748 of file LibMkKernel_mk.h.

{
  return __MkCheckX(MkRuntimeC,&MkRuntimeRLS) ? MkRT : MkRuntimeInit( MkRT );
}

MkRuntimeInit()

MK_EXTERN MK_RT libmkkernel::MkRuntimeInit

(

MK_RT const

mkrt

)

initialize MkRuntimeRLS …

Here is the caller graph for this function:

Variable Documentation

MkRuntimeRLS

MK_EXTERN_DATA MkThreadLocal struct MkRuntimeS libmkkernel::MkRuntimeRLS

RLS …

this is the runtime defined as MkThreadLocal

Definition at line 11740 of file LibMkKernel_mk.h.