MkRuntimeC_C_API

MkRuntimeC - The class known as mkrt or runtime is the main libmkkernel application environment … More...

Collaboration diagram for MkRuntimeC_C_API:

Topics
	MkRtExtC
	MkRtExtS - extend the MkRuntimeC with a library specific feature …
	MkRuntimeC_Class_C_API
	MkRuntimeC - define the class …
	MkRuntimeC_Interface_C_API
	MkRuntimeC - The MkRuntimeRLS, a thread-local storage for application-global data …
	MkRuntimeC_Config_C_API
	MkRuntimeC - various functions to configure the MkRuntimeRLS (only C) …
	MkRuntimeC_Info_C_API
	MkRuntimeC - various functions to print information about the rt …

Data Structures
struct	MkRuntimeS
	The MkRuntimeS provide a per-thread environment for LibMkKernel … More...

Detailed Description

MkRuntimeC - The class known as mkrt or runtime is the main libmkkernel application environment …

The runtime is automatically created as thread-local-storage at startup, so that each new thread receives a thread-specific runtime. Each instance of the thread has a link to the runtime it was created in:

• MkOBJ_R(instance).objRt = MkObjectS::objRt

runtime-separation

• The runtime and also the runtime-related-thread in the Programming-Language-Micro-Kernel (PLMK) are treated as an independent-process without any process overhead.
• The runtime is completly independent of any other runtime and can also be used in a separate process without changing the code.
• The technology behind the so-called runtime-separation is the libmkkernel technology.

the runtime provide the following features

• The default-error -> MkErrorC
• The runtime-local-storage (RLS) -> MkKernel_Storage_C_API
• The application wide configuration data like debug, logfile or silent
• The storage and the management of the Programming-Language-Micro-Kernel (PLMK) default-types like MkBufferC -> MkTypeC_C_API

THREAD ENABLED LIBRARY

The thread-enabled-libry is a library compiled with the --enable-thread configure option of Nhi1Config

RUNTIME DEFAULT

The Programming-Language-Micro-Kernel (PLMK) always has one runtime per thread called the runtime-default. This runtime is created at MkSetup and destroyed at MkCleanup.
The runtime-enabled-function always get the runtime-default as first argument in a doc_mk_c_thread-enabled-library.

RUNTIME INTERFACE

‍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