libmkkernel 9.0
No Matches
Data Structures | Macros | Typedefs | Functions | Variables

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...


#define MkThreadLocal   __thread
#define MK_RT_IS_ARG   1
#define MK_RT_ARGS_ONLY   MK_RT mkrt
#define MK_RT_CALL_ONLY   mkrt
#define MK_RT_CALL_O(o)   MkRT_O(o),
#define MK_RT_CALL_X(x)   MkRT_X(x),
#define MK_RT_NULL   NULL,
#define MK_RT_PTR   mkrt
#define MK_RT_REF   (*mkrt)
#define MK_RT_CALL_RT(ptr)   ptr,
#define MK_RT_PARSER_ONLY   MK_RT_ARGS_ONLY __parser__(internal,default=N#RUNTIME)
#define MK_RT_ATTR_NONNULL_1   __attribute__((nonnull(2)))
#define MK_RT_ATTR_NONNULL_2   __attribute__((nonnull(3)))
#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_HDL   __attribute__((nonnull(2)))
#define MK_RT_ATTR_HDL
#define MK_RT_ATTR_HDL_CHECK(x)   assert(x!=NULL)
#define MK_RT_ATTR_RUNTIME_CHECK_XN(x)   MkRtSetup_XN_RT(x)
#define MK_RT_ATTR_RUNTIME_CHECK_ON(x)   MkRtSetup_ON_RT(x)
#define MK_RT_ATTR_NONNULL_1_CHECK(x)   assert(x!=NULL)
#define MK_RT_ATTR_NONNULL_2_CHECK(x)   assert(x!=NULL)


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


MK_EXTERN MK_RT MkRuntimeInit (MK_RT const mkrt)
 initialize MkRuntimeRLS
MK_RT MkRuntimeGet (void)
 return a initialized MkRuntimeRLS


MK_EXTERN_DATA MkThreadLocal struct MkRuntimeS MkRuntimeRLS
 RLS …


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:

Example from "LibLcConfig_java.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) {
void LcSetup(void) {
sLcRuntimeCallback.mkrt = mkrt;
sLcRuntimeCallback.cb = NS(sLcRuntimeCallback);
// class specific initialization
MkRuntimeCallbackAdd( &sLcRuntimeCallback );
#define MkTypeCreate(clsV, basicV, identV)
Definition kernel_mk.h:5588
#define MkThreadLocal
Definition kernel_mk.h:2362
Definition kernel_mk.h:2366
MK_EXTERN void MkRuntimeCallbackAdd(struct MkRuntimeCallbackS *cbdata, MK_RT mkrt, MkRuntimeInitF rt_callback, MK_STRN ident)
add a callback to the runtime …
keep callback related data …
MkRuntimeInitF cb
required data
struct MkRuntimeS * mkrt
required data
The MkRuntimeS provide a per-thread environment for LibMkKernel …
define a Type object …
Definition kernel_mk.h:4745
MK_EXTERN void MkRuntimeCallbackAdd (struct MkRuntimeCallbackS *cbdata, MK_RT mkrt, MkRuntimeInitF rt_callback, MK_STRN ident)
 add a callback to the runtime
MK_EXTERN void MkRuntimeCallbackDel (struct MkRuntimeCallbackS *cbdata)
 delete a callback from the runtime


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

Detailed Description

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

read also: MkRuntimeC DETAIL

The goal of the runtime-interface is to provide the best performane for thread and non-thread.
  • On thread a runtime-cache is preferred.
  • On non-thread the direct-access to the MkRuntimeRLS is preferred.
  • The libmkkernel was build with configure --enable-threads ....
  • Every thread has its 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-acces (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.
  • The libmkkernel was build with configure --disable-threads ....
  • The process has only one MkRuntimeRLS
  • The MkRuntimeRLS is created as S)tatic-G)lobal-S)torage (SGS).
  • The MkRuntimeRLS can be reached via the macro MkRT, compile-time-resolving with a direct-access (fast)
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 thread.
  • In a non-threaded-environment only one MkRuntimeRLS exists.
  • Every new MkRuntimeRLS have to be initialized with MkRuntimeGet.
    • The initialization is always done in the MkRtSetup_xxx macro at the FIRST MkRuntimeRLS access at a NEW thread.
    • Every initialization is done only once.
threaded versa non-threaded:
The MkRuntimeRLS access is different for threaded and non-threaded.
  • To avoid the expensive MkRT function call in a threaded-environment the MK_RT_xxx and MkRtSetup_xxx macros are used to access the MkRuntimeRLS.
what storage resolve access how speed
threaded TLS run-time local-cache via mkrt fast
non-threaded SGS compile-time direct via MkRT fast
Create the local-cache:
The local-cache is only required for a threaded-environment and defined as mkrt variable initialized with a pointer to the MkRuntimeRLS :
  • In a runtime-aware function the local-cache is always as first argument in the function.
    void myfunc( get-local-cache arg1, arg2, arg... ) {
  • In a non-runtime-aware function the local-cache have to be created because the first argument is not available:
    void myfunc( arg1, arg2, arg... ) {
    define-local-cache ...
In a non-runtime-aware function the local-cache is created from the instance or from the MkRT.
source local-cache is created with example speed
instance MkRtSetup_O , MkRtSetup_X MkSetup_X(instance) fast
MkRT MkRtSetup_NULL MkSetup_NULL slow
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
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
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, ...) { ... }
#define MK_RT_ARGS
Definition kernel_mk.h:2365
Example: call a runtime-aware function
myfunc ( MK_RT_CALL 1 , 2 , ... );
#define MK_RT_CALL
Definition kernel_mk.h:2367
Example: setup of the runtime in a non-runtime-aware function with instance argument
void myfunc (MK_RT_ARGS MK_BUF mybuf, MK_INT someValue) {
MkRtSetup_X(mybuf); // define mkrt local cache
MK_RT_REF.debug = someValue; // use the local-cache as reference to access the MkRuntimeRLS
signed int MK_INT
4 byte integer data-type
Definition kernel_mk.h:2642
#define MkRtSetup_X(x)
#define MK_RT_REF
Definition kernel_mk.h:2374
The ABSTRACT-CLASS used to store a native-type-data-item defined by PRIMITIVE TYPE …
Definition kernel_mk.h:6194
All functions and macros used are related to the namespace of the library:
  • The namespace from libmkkernel is mk or Mk or MK
  • The namespace from libmqmsgque is mq or Mq or MQ
  • The namespace from liblcconfig is lc or Lc or LC
  • ...

Macro Definition Documentation



Definition at line 2365 of file kernel_mk.h.


#define MK_RT_ARGS_ONLY   MK_RT mkrt

Definition at line 2364 of file kernel_mk.h.


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

Definition at line 2381 of file kernel_mk.h.


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

Definition at line 2382 of file kernel_mk.h.


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

Definition at line 2383 of file kernel_mk.h.

◆ MK_RT_ATTR_HDL [1/2]

#define MK_RT_ATTR_HDL   __attribute__((nonnull(2)))

Definition at line 2387 of file kernel_mk.h.

◆ MK_RT_ATTR_HDL [2/2]

#define MK_RT_ATTR_HDL

Definition at line 2387 of file kernel_mk.h.


#define MK_RT_ATTR_HDL_CHECK (   x)    assert(x!=NULL)

Definition at line 2421 of file kernel_mk.h.


#define MK_RT_ATTR_NONNULL_1   __attribute__((nonnull(2)))

Definition at line 2379 of file kernel_mk.h.


#define MK_RT_ATTR_NONNULL_1_CHECK (   x)    assert(x!=NULL)

Definition at line 2426 of file kernel_mk.h.


#define MK_RT_ATTR_NONNULL_2   __attribute__((nonnull(3)))

Definition at line 2380 of file kernel_mk.h.


#define MK_RT_ATTR_NONNULL_2_CHECK (   x)    assert(x!=NULL)

Definition at line 2427 of file kernel_mk.h.



Definition at line 2386 of file kernel_mk.h.


#define MK_RT_ATTR_RUNTIME_CHECK_ON (   x)    MkRtSetup_ON_RT(x)

Definition at line 2425 of file kernel_mk.h.


#define MK_RT_ATTR_RUNTIME_CHECK_XN (   x)    MkRtSetup_XN_RT(x)

Definition at line 2424 of file kernel_mk.h.



Definition at line 2367 of file kernel_mk.h.



Definition at line 2371 of file kernel_mk.h.



Definition at line 2370 of file kernel_mk.h.


#define MK_RT_CALL_O (   o)    MkRT_O(o),

Definition at line 2368 of file kernel_mk.h.


#define MK_RT_CALL_ONLY   mkrt

Definition at line 2366 of file kernel_mk.h.


#define MK_RT_CALL_RT (   ptr)    ptr,

Definition at line 2376 of file kernel_mk.h.


#define MK_RT_CALL_X (   x)    MkRT_X(x),

Definition at line 2369 of file kernel_mk.h.


#define MK_RT_IS_ARG   1

Definition at line 2363 of file kernel_mk.h.


#define MK_RT_NULL   NULL,

Definition at line 2372 of file kernel_mk.h.



Definition at line 2378 of file kernel_mk.h.


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

Definition at line 2377 of file kernel_mk.h.


#define MK_RT_PTR   mkrt

Definition at line 2373 of file kernel_mk.h.


#define MK_RT_REF   (*mkrt)

Definition at line 2374 of file kernel_mk.h.



Definition at line 2375 of file kernel_mk.h.

◆ MkRT

#define MkRT   (&MkRuntimeRLS)

Definition at line 12785 of file kernel_mk.h.

◆ MkRT_O

#define MkRT_O (   o)    ((o) && (*o).objRt ? (*o).objRt : MkRuntimeGet())

Definition at line 12789 of file kernel_mk.h.


#define MkRT_ON (   o)    ( (*o).objRt ? (*o).objRt : MkRuntimeGet())

Definition at line 12792 of file kernel_mk.h.


#define MkRT_ONN (   o)    ((*o).objRt)

Definition at line 12791 of file kernel_mk.h.

◆ MkRT_R

#define MkRT_R   (MkRuntimeRLS)

Definition at line 12786 of file kernel_mk.h.

◆ MkRT_X

#define MkRT_X (   x)    ((x) && MkOBJ_R(x).objRt ? MkOBJ_R(x).objRt : MkRuntimeGet())

Definition at line 12790 of file kernel_mk.h.


#define MkRT_XN (   x)    ( MkOBJ_R(x).objRt ? MkOBJ_R(x).objRt : MkRuntimeGet())

Definition at line 12793 of file kernel_mk.h.

◆ MkRtSetup_NULL

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

Definition at line 12807 of file kernel_mk.h.

◆ MkRtSetup_NULL_RT

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

Definition at line 12816 of file kernel_mk.h.

◆ MkRtSetup_O

#define MkRtSetup_O (   o)    MK_RT_UNUSED MK_RT const mkrt = MkRT_O(o)

Definition at line 12803 of file kernel_mk.h.

◆ MkRtSetup_O_RT

#define MkRtSetup_O_RT (   o)    if (mkrt == NULL) mkrt = MkRT_O(o)

Definition at line 12812 of file kernel_mk.h.

◆ MkRtSetup_ON

#define MkRtSetup_ON (   o)    MK_RT_UNUSED MK_RT const mkrt = MkRT_ON(o)

Definition at line 12806 of file kernel_mk.h.

◆ MkRtSetup_ON_RT

#define MkRtSetup_ON_RT (   o)    if (mkrt == NULL) mkrt = MkRT_ON(o)

Definition at line 12815 of file kernel_mk.h.

◆ MkRtSetup_RT

#define MkRtSetup_RT (   r)    MK_RT_UNUSED MK_RT const mkrt = r;

Definition at line 12808 of file kernel_mk.h.

◆ MkRtSetup_X

#define MkRtSetup_X (   x)    MK_RT_UNUSED MK_RT const mkrt = MkRT_X(x)

Definition at line 12804 of file kernel_mk.h.

◆ MkRtSetup_X_RT

#define MkRtSetup_X_RT (   x)    if (mkrt == NULL) mkrt = MkRT_X(x)

Definition at line 12813 of file kernel_mk.h.

◆ MkRtSetup_XN

#define MkRtSetup_XN (   x)    MK_RT_UNUSED MK_RT const mkrt = MkRT_XN(x)

Definition at line 12805 of file kernel_mk.h.

◆ MkRtSetup_XN_RT

#define MkRtSetup_XN_RT (   x)    if (mkrt == NULL) mkrt = MkRT_XN(x)

Definition at line 12814 of file kernel_mk.h.

◆ MkRtSetupFromRtExt

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

Definition at line 12809 of file kernel_mk.h.

◆ MkThreadLocal

#define MkThreadLocal   __thread

Definition at line 2362 of file kernel_mk.h.

Typedef Documentation

◆ MkRuntimeInitF

typedef void( * 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
MkRuntimeCallbackAdd MkRuntimeCallbackDel

Definition at line 12839 of file kernel_mk.h.

Function Documentation

◆ MkRuntimeCallbackAdd()

MK_EXTERN void 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→alloc_data and the type-local alloc-callbacks MkTypeS::objalloc→alloc_createF}, MkTypeS::objalloc→alloc_deleteF. The memory-allocator is thread-local because the cache is thread-local including the predefined objects. Without a thread-local type and a thread-local memory-allocater every acces to the memory-allocator (including the cache) have to be protected by a semaphore.

Example from Filter4.c Defined a new 'type'.

#define TRANSCTX ((struct FilterCtxS*const)mqctx)
#define SETUP_ctx struct FilterCtxS*const ctx = TRANSCTX;
struct FilterCtxS {
struct MqContextS mqctx;
MQ_DMP *itm;
int *errcnt;
MK_NUM rIdx;
MK_NUM wIdx;
MK_NUM size;
// types are runtime-(thread)-local
static MK_TYP Filter4TT = NULL;
#define Filter4T ((typeof(MqContextC_T)) Filter4TT)
int32_t MK_NUM
array size data-type ('num' items in array …
Definition kernel_mk.h:2679

Example from Filter4.c Initialize a new 'type' once per runtime (thread.)

static MQ_CTX Filter4Create (
MK_RT_ARGS MQ_CTX const tmpl
// use the new type "Filter4TT"
MQ_CTX const mqctx = MqContextCreate(Filter4TT,tmpl);
mqctx->setup.isServer = true;
mqctx->setup.ServerSetup.fCall = FilterSetup;
mqctx->setup.ServerCleanup.fCall = FilterCleanup;
mqctx->setup.Event.fCall = FilterEvent;
mqctx->setup.EventIsServer = true;
mqctx->setup.ignoreExit = true;
return mqctx;
static enum MkErrorE
*contextP = Filter4Create ( MK_RT_CALL tmpl);
return MK_OK;
// [initial_example]
main (
const int argc,
MK_STRN argv[]
// new types are created per-runtime
Filter4TT = MkTypeDup2(MqContextC_TT,"Filter4");
Filter4TT->objsize = sizeof(struct FilterCtxS);
// the parent-context
MK_BFL args = MkBufferListCreateVC (argc, argv);
// create the factory and set the "initial" attribute.
// with "initial" set every new context get the "Filter4Factory" as factory.
MqFactoryAdd(MK_ERROR_PANIC, Filter4Factory, NULL, NULL, NULL, NULL, NULL, NULL, NULL, "Filter4")
// instance created WITHOUT "MqFactoryNew" but "initial" from above garantee the right "factory-aware" setup.
// WITHOUT "initial" from above there is NO link between the new instance and the "Filter4Factory".
MQ_CTX mqctx = Filter4Create( MK_RT_CALL NULL);
// create the link
MqLinkCreate_E (mqctx, args);
// start event-loop and wait forever
// finish and exit
MqExit_1 (mqctx);
#define MkTypeDup2(...)
#define MkBufferListCreateVC(...)
#define MkBufferListDelete(x)
collection for the different error-codes …
Definition kernel_mk.h:3111
request the user defined timeout value from the MqTimeout configuration value …
Definition kernel_mk.h:3172
everything is OK, no error available (persistent)
Definition kernel_mk.h:3112
constant string pointer data-type
Definition kernel_mk.h:2745
The CLASS used to store a list of MkBufferS items into a flat array…
Definition kernel_mk.h:9037
size_t objsize
the size of the new object created with this type, used in malloc
Definition kernel_mk.h:4759
See also

◆ MkRuntimeCallbackDel()

MK_EXTERN void MkRuntimeCallbackDel ( struct MkRuntimeCallbackS cbdata)

delete a callback from the runtime

See also

◆ MkRuntimeGet()

MK_RT MkRuntimeGet ( void  )

return a initialized MkRuntimeRLS

Definition at line 12948 of file kernel_mk.h.

◆ MkRuntimeInit()

MK_EXTERN MK_RT MkRuntimeInit ( MK_RT const  mkrt)

initialize MkRuntimeRLS

+ Here is the caller graph for this function:

Variable Documentation

◆ MkRuntimeRLS


Definition at line 12940 of file kernel_mk.h.