MkRuntimeC_Interface_C_API

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

Collaboration diagram for MkRuntimeC_Interface_C_API:

Data Structures
struct	MkRuntimeCallbackS
	keep callback related data … More...

Macros
#define	MK_RT_ATTR_FORMAT_1   __attribute__((format (printf, 1+MK_RT_SHIFT, 2+MK_RT_SHIFT)));
#define	MK_RT_ATTR_FORMAT_2   __attribute__((format (printf, 2+MK_RT_SHIFT, 3+MK_RT_SHIFT)))
#define	MK_RT_ATTR_FORMAT_4   __attribute__((format (printf, 4+MK_RT_SHIFT, 5+MK_RT_SHIFT)))
#define	__MK_ATTR_RT_RUNTIME
#define	__MK_ATTR_RT_INSTANCE
#define	__MK_ATTR_INSTANCE
#define	MK_INSTANCE_HDL(x)
#define	MK_ATTR_INSTANCE   __MK_ATTR_INSTANCE
#define	MK_ATTR_RT_INSTANCE   __MK_ATTR_RT_RUNTIME __MK_ATTR_RT_INSTANCE
#define	MK_ATTR_STATIC   __parser__(static)
#define	MK_ATTR_RT_STATIC   __MK_ATTR_RT_RUNTIME __parser__(static)
#define	MK_INSTANCE_RT_X(x)
#define	MK_INSTANCE_RT_XN(x)
#define	MK_INSTANCE_RT_O(o)
#define	MK_INSTANCE_RT_ON(o)
#define	MK_DESTRUCTOR_RT_X(c, x)
#define	MK_STATIC_RT   MkRtSetup_NULL_RT

Typedefs
typedef void(*	MkRuntimeInitF) (MK_RT mkrt)
	additional runtime initialization function …

Functions
MK_RT	MkRuntimeSetup (MK_RT const mkrt)
	initialize MkRuntimeRLS …
void	MkRuntimeCleanup (MK_RT mkrt)
	cleanup MkRuntimeRLS …
static MK_RT	MkRuntimeGet (void)
	return a initialized MkRuntimeRLS …
static MK_RT	MkRuntimeGetFromObj (MK_OBJ obj)
	return the initialized MkRuntimeRLS from an obj …

Variables
__thread struct MkRuntimeS	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 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 ); ... }
typedef struct MkRuntimeCallbackS	MkRuntimeCallbackS
	keep callback related data …
size_t	MkRuntimeCallbackAdd (MK_RT mkrt, MkRuntimeCallbackS *cbdata, MkRuntimeInitF rt_callback, MK_STRN ident)
	add a callback to the runtime …
void	MkRuntimeCallbackDel (MkRuntimeCallbackS *cbdata)
	delete a callback from the runtime …

META_HAS_THREAD
#define	MkThreadLocal   __thread
#define	MK_RT_SHIFT   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_PARSER_RT_ONLY   MK_RT_ARGS_ONLY __parser__(internal,default=N#RUNTIME)
#define	MK_PARSER_RT   MK_PARSER_RT_ONLY,

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_ON_RT(o)
#define	MkRtSetup_X_RT(x)
#define	MkRtSetup_XN_RT(x)
#define	MkRtSetup_NULL_RT   if (mkrt == NULL) mkrt = MkRuntimeGet()
#define	AllRtSetup_O(o)
#define	AllRtSetup_ON(o)
#define	AllRtSetup_X(x)
#define	AllRtSetup_XN(x)
#define	AllRtSetup_NULL   MkRtSetup_NULL

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 libmkkernel 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 MkObjectS::objRt attribute.

on non-thread

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

• The libmkkernel 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_PARSER_RT	MK_RT_CALL
no args	MK_RT_ARGS_ONLY	MK_PARSER_RT_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_ATTR_INSTANCE

#define __MK_ATTR_INSTANCE

Definition at line 866 of file LibMkKernel_mk.h.

__MK_ATTR_RT_INSTANCE

#define __MK_ATTR_RT_INSTANCE

Definition at line 865 of file LibMkKernel_mk.h.

__MK_ATTR_RT_RUNTIME

#define __MK_ATTR_RT_RUNTIME

Definition at line 857 of file LibMkKernel_mk.h.

AllRtSetup_NULL

#define AllRtSetup_NULL   MkRtSetup_NULL

Definition at line 11959 of file LibMkKernel_mk.h.

AllRtSetup_O

#define AllRtSetup_O

(

o

)

Value:

MkRtSetup_O(o)

Definition at line 11955 of file LibMkKernel_mk.h.

AllRtSetup_ON

#define AllRtSetup_ON

(

o

)

Value:

MkRtSetup_ON(o)

Definition at line 11956 of file LibMkKernel_mk.h.

AllRtSetup_X

#define AllRtSetup_X

(

x

)

Value:

MkRtSetup_X(x)

Definition at line 11957 of file LibMkKernel_mk.h.

AllRtSetup_XN

#define AllRtSetup_XN

(

x

)

Value:

MkRtSetup_XN(x)

Definition at line 11958 of file LibMkKernel_mk.h.

MK_ATTR_INSTANCE

#define MK_ATTR_INSTANCE   __MK_ATTR_INSTANCE

Definition at line 871 of file LibMkKernel_mk.h.

MK_ATTR_RT_INSTANCE

#define MK_ATTR_RT_INSTANCE   __MK_ATTR_RT_RUNTIME __MK_ATTR_RT_INSTANCE

Definition at line 872 of file LibMkKernel_mk.h.

MK_ATTR_RT_STATIC

#define MK_ATTR_RT_STATIC   __MK_ATTR_RT_RUNTIME __parser__(static)

Definition at line 874 of file LibMkKernel_mk.h.

MK_ATTR_STATIC

#define MK_ATTR_STATIC   __parser__(static)

Definition at line 873 of file LibMkKernel_mk.h.

MK_DESTRUCTOR_RT_X

#define MK_DESTRUCTOR_RT_X	(		c,
			x )

Value:

                                        MK_INSTANCE_HDL(x);        \
                                        if (!MkCheckNN(c,x)) return;    /* do NOT delete an invalid pointer */ \
                                        MkRtSetup_XN_RT(x)

Definition at line 881 of file LibMkKernel_mk.h.

#define MK_DESTRUCTOR_RT_X(c,x)         MK_INSTANCE_HDL(x);        \
                                        if (!MkCheckNN(c,x)) return;    /* do NOT delete an invalid pointer */ \
                                        MkRtSetup_XN_RT(x)

MK_INSTANCE_HDL

#define MK_INSTANCE_HDL

(

x

)

Value:

assert(x!=NULL)

Definition at line 867 of file LibMkKernel_mk.h.

MK_INSTANCE_RT_O

#define MK_INSTANCE_RT_O

(

o

)

Value:

MK_INSTANCE_HDL(o); MkRtSetup_ON_RT(o)

Definition at line 879 of file LibMkKernel_mk.h.

MK_INSTANCE_RT_ON

#define MK_INSTANCE_RT_ON

(

o

)

Value:

MkRtSetup_O_RT(o)

Definition at line 880 of file LibMkKernel_mk.h.

MK_INSTANCE_RT_X

#define MK_INSTANCE_RT_X

(

x

)

Value:

MK_INSTANCE_HDL(x); MkRtSetup_XN_RT(x)

Definition at line 877 of file LibMkKernel_mk.h.

MK_INSTANCE_RT_XN

#define MK_INSTANCE_RT_XN

(

x

)

Value:

MkRtSetup_X_RT(x)

Definition at line 878 of file LibMkKernel_mk.h.

MK_PARSER_RT

#define MK_PARSER_RT   MK_PARSER_RT_ONLY,

Definition at line 825 of file LibMkKernel_mk.h.

MK_PARSER_RT_ONLY

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

Definition at line 824 of file LibMkKernel_mk.h.

MK_RT_ARGS

#define MK_RT_ARGS   MK_RT_ARGS_ONLY,

Definition at line 811 of file LibMkKernel_mk.h.

MK_RT_ARGS_ONLY

#define MK_RT_ARGS_ONLY   MK_RT mkrt

Definition at line 810 of file LibMkKernel_mk.h.

MK_RT_ATTR_FORMAT_1

#define MK_RT_ATTR_FORMAT_1   __attribute__((format (printf, 1+MK_RT_SHIFT, 2+MK_RT_SHIFT)));

Definition at line 851 of file LibMkKernel_mk.h.

MK_RT_ATTR_FORMAT_2

#define MK_RT_ATTR_FORMAT_2   __attribute__((format (printf, 2+MK_RT_SHIFT, 3+MK_RT_SHIFT)))

Definition at line 852 of file LibMkKernel_mk.h.

MK_RT_ATTR_FORMAT_4

#define MK_RT_ATTR_FORMAT_4   __attribute__((format (printf, 4+MK_RT_SHIFT, 5+MK_RT_SHIFT)))

Definition at line 853 of file LibMkKernel_mk.h.

MK_RT_CALL

#define MK_RT_CALL   MK_RT_CALL_ONLY,

Definition at line 813 of file LibMkKernel_mk.h.

MK_RT_CALL_NULL

#define MK_RT_CALL_NULL   MK_RT_CALL_NULL_ONLY,

Definition at line 817 of file LibMkKernel_mk.h.

MK_RT_CALL_NULL_ONLY

#define MK_RT_CALL_NULL_ONLY   MkRT

Definition at line 816 of file LibMkKernel_mk.h.

MK_RT_CALL_O

#define MK_RT_CALL_O

(

o

)

Value:

MkRT_O(o),

Definition at line 814 of file LibMkKernel_mk.h.

MK_RT_CALL_ONLY

#define MK_RT_CALL_ONLY   mkrt

Definition at line 812 of file LibMkKernel_mk.h.

MK_RT_CALL_RT

#define MK_RT_CALL_RT

(

ptr

)

Value:

ptr,

Definition at line 823 of file LibMkKernel_mk.h.

MK_RT_CALL_X

#define MK_RT_CALL_X

(

x

)

Value:

MkRT_X(x),

Definition at line 815 of file LibMkKernel_mk.h.

MK_RT_NULL

#define MK_RT_NULL   NULL,

Definition at line 818 of file LibMkKernel_mk.h.

MK_RT_PTR

#define MK_RT_PTR   mkrt

Definition at line 819 of file LibMkKernel_mk.h.

MK_RT_REF

#define MK_RT_REF   (*mkrt)

Definition at line 820 of file LibMkKernel_mk.h.

MK_RT_REF_NULL

#define MK_RT_REF_NULL   (MkRuntimeRLS)

Definition at line 821 of file LibMkKernel_mk.h.

MK_RT_SHIFT

#define MK_RT_SHIFT   1

Definition at line 809 of file LibMkKernel_mk.h.

MK_RT_UNUSED

#define MK_RT_UNUSED   MK_UNUSED

Definition at line 822 of file LibMkKernel_mk.h.

MK_STATIC_RT

#define MK_STATIC_RT   MkRtSetup_NULL_RT

Definition at line 884 of file LibMkKernel_mk.h.

MkRT

#define MkRT   (&MkRuntimeRLS)

Definition at line 11922 of file LibMkKernel_mk.h.

MkRT_O

#define MkRT_O

(

o

)

Value:

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

Definition at line 11926 of file LibMkKernel_mk.h.

MkRT_ON

#define MkRT_ON

(

o

)

Value:

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

Definition at line 11929 of file LibMkKernel_mk.h.

MkRT_ONN

#define MkRT_ONN

(

o

)

Value:

((*o).objRt)

Definition at line 11928 of file LibMkKernel_mk.h.

MkRT_R

#define MkRT_R   (MkRuntimeRLS)

Definition at line 11923 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 11927 of file LibMkKernel_mk.h.

MkRT_XN

#define MkRT_XN

(

x

)

Value:

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

Definition at line 11930 of file LibMkKernel_mk.h.

MkRtSetup_NULL

#define MkRtSetup_NULL   MK_RT_UNUSED MK_RT const mkrt = MkRuntimeGet()

Definition at line 11944 of file LibMkKernel_mk.h.

MkRtSetup_NULL_RT

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

Definition at line 11953 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 11940 of file LibMkKernel_mk.h.

MkRtSetup_O_RT

#define MkRtSetup_O_RT

(

o

)

Value:

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

Definition at line 11949 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 11943 of file LibMkKernel_mk.h.

MkRtSetup_ON_RT

#define MkRtSetup_ON_RT

(

o

)

Value:

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

Definition at line 11950 of file LibMkKernel_mk.h.

MkRtSetup_RT

#define MkRtSetup_RT

(

r

)

Value:

MK_RT_UNUSED MK_RT const mkrt = r

Definition at line 11945 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 11941 of file LibMkKernel_mk.h.

MkRtSetup_X_RT

#define MkRtSetup_X_RT

(

x

)

Value:

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

Definition at line 11951 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 11942 of file LibMkKernel_mk.h.

MkRtSetup_XN_RT

#define MkRtSetup_XN_RT

(

x

)

Value:

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

Definition at line 11952 of file LibMkKernel_mk.h.

MkRtSetupFromRtExt

#define MkRtSetupFromRtExt

(

rtx

)

Value:

MK_RT_UNUSED MK_RT const mkrt = MkRTEXT_R(rtx).mkrtHead

Definition at line 11946 of file LibMkKernel_mk.h.

MkThreadLocal

#define MkThreadLocal   __thread

Definition at line 808 of file LibMkKernel_mk.h.

Typedef Documentation

MkRuntimeCallbackS

typedef struct MkRuntimeCallbackS MkRuntimeCallbackS

keep callback related data …

MkRuntimeInitF

typedef void( * MkRuntimeInitF) (MK_RT mkrt)

additional runtime initialization function …

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

See also

MkRuntimeCallbackAdd MkRuntimeCallbackDel

Definition at line 11988 of file LibMkKernel_mk.h.

Function Documentation

MkRuntimeCallbackAdd()

size_t MkRuntimeCallbackAdd	(	MK_RT	mkrt,
		MkRuntimeCallbackS *	cbdata,
		MkRuntimeInitF	rt_callback,
		MK_STRN	ident )

add a callback to the runtime …

The MkRuntimeCallbackAdd and MkRuntimeCallbackDel belong to the low-level-api and is primary used for language-integration into the Programming-Language-Micro-Kernel (PLMK).

The rt_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

Example to integrate the jvmkkernel extension into the PLMK

1. define the rt_callback

   static void NS(sMkRuntimeCallback) ( MK_RT_ARGS_ONLY ) {
     // BEGIN-INIT - created by 'jv_MqS.tcl -i NHI1_HOME/theKernel/c/gen/c_mkkernel.meta' - DO NOT change
    
     NS(MkBufferListC_Init)   (MK_RT_CALL_ONLY) ;
     NS(MkBufferC_Init)       (MK_RT_CALL_ONLY) ;
     NS(MkBufferStreamC_Init) (MK_RT_CALL_ONLY) ;
     NS(MkErrorC_Init)        (MK_RT_CALL_ONLY) ;
     NS(MkLogFileC_Init)      (MK_RT_CALL_ONLY) ;
     NS(MkObjectC_Init)       (MK_RT_CALL_ONLY) ;
     NS(MkRuntimeC_Init)      (MK_RT_CALL_ONLY) ;
    
     // END-INIT - created by 'jv_MqS.tcl -i NHI1_HOME/theKernel/c/gen/c_mkkernel.meta' - DO NOT change
   }

2. initialize the MkRuntimeCallbackS

   static struct MkRuntimeCallbackS NS(sMkRuntimeCallbackData) = {0};

3. on java extension startup

   JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *jvm, void *reserved)
   {
     MkSetup();
     MkRtSetup_NULL;
     MkRuntimeCallbackAdd( MK_RT_CALL &NS(sMkRuntimeCallbackData), NS(sMkRuntimeCallback), "JvKernel" );
   }

   ...

   JNIEXPORT void JNICALL JNI_OnUnload(JavaVM *jvm, void *reserved)
   {
     MkRuntimeCallbackDel( &NS(sMkRuntimeCallbackData) );
     MkCleanup();
   }

4. the NS(...) macro create a proper function-name in the .dll/.so file

   000000000000caef t jvmkkernel_sMkRuntimeCallback
   00000000000259a0 b jvmkkernel_sMkRuntimeCallbackData
   

Parameters

[in]	cbdata	(non NULL) - struc to register the callback. memory have to be initialized to 0 -> MkRuntimeCallbackS myCbReg = {0}.
[in]	mkrt	(non NULL) - initial MkRuntimeC. the rt_callback will be called with mkrt to initialize first custom-runtime in MkRuntimeCallbackAdd
[in]	rt_callback	(non NULL) - callback to initialize new custom runtime string to identify the rt_callback runtime.
[in]	ident	(non NULL) - string to identify the rt_callback runtime.

Returns

• The rtId is a unique value to identify the cbdata.
• The rtId can be used as array-index.
• The rtId is 0 <= rtId < #MkExtension_size

See also

MkRuntimeCallbackDel

MkRuntimeCallbackDel()

void MkRuntimeCallbackDel

(

MkRuntimeCallbackS *

cbdata

)

delete a callback from the runtime …

See also

MkRuntimeCallbackAdd

MkRuntimeCleanup()

void MkRuntimeCleanup

(

MK_RT

mkrt

)

cleanup MkRuntimeRLS …

Do not call this function directly, because types will be cleared.

Only call this function via MkCleanup.

MkRuntimeGet()

static MK_RT MkRuntimeGet ( void )

inlinestatic

return a initialized MkRuntimeRLS …

Definition at line 12162 of file LibMkKernel_mk.h.

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

MkRuntimeGetFromObj()

static MK_RT MkRuntimeGetFromObj ( MK_OBJ obj )

inlinestatic

return the initialized MkRuntimeRLS from an obj …

Definition at line 12169 of file LibMkKernel_mk.h.

  {
  return MkRT_O(obj);
}

MkRuntimeSetup()

MK_RT MkRuntimeSetup

(

MK_RT const

mkrt

)

initialize MkRuntimeRLS …

Do not call this function directly, because if MkRuntimeRLS is already initialized, MkRuntimeCleanup will be called first and all libmkkernel types will be cleared.

Only call MkRuntimeGet to get the mkrt and use MkSetup to setup the MkRuntimeRLS.

Here is the caller graph for this function:

Variable Documentation

MkRuntimeRLS

__thread struct MkRuntimeS MkRuntimeRLS

extern

RLS …

this is the runtime defined as MkThreadLocal