MkRuntimeC_CC_API

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

Collaboration diagram for MkRuntimeC_CC_API:

Topics
	MkRuntimeC_Class_CC_API
	MkRuntimeC_Config_CC_API
	MkRuntimeC - various functions to configure the MkRuntimeRLS (only C) …
	MkRuntimeC_Info_CC_API
	MkRuntimeC - various functions to print information about the rt …

Classes
struct	ccmkkernel::MkRuntimeC_A
	The MkRuntimeS provide a per-thread environment for ccmkkernel … → C-API: libmkkernel::MkRuntimeS More...
class	ccmkkernel::MkRuntimeC
	The MkRuntimeS provide a per-thread environment for ccmkkernel … → C-API: libmkkernel::MkRuntimeS More...

Functions
	ccmkkernel::MkRuntimeC::MkRuntimeC (MK_RT hdl)
static MkRuntimeC *	ccmkkernel::MkRuntimeC::MkRuntimeC_ObjNew (MK_RT_ARGS MK_RT hdl)
	return MkRuntimeC from LibMsgqueObject
MK_RT	ccmkkernel::MkRuntimeC::getRT () const
	return the LibMsgqueObject from current MkRuntimeC instance
MK_RT	ccmkkernel::MkRuntimeC::getRT__null_allow () const
	return the LibMsgqueObject from current MkRuntimeC instance
MK_RTN	ccmkkernel::MkRuntimeC::getRTN () const
	(const) return the LibMsgqueObject from current MkRuntimeC instance
MK_RTN	ccmkkernel::MkRuntimeC::getRTN__null_allow () const
	(const) return the LibMsgqueObject from current MkRuntimeC instance
static MK_RT	ccmkkernel::MkRuntimeC::getRT (MkRuntimeC *clsHdl)
	return LibMsgqueObject from current MkRuntimeC pointer
static MK_RT	ccmkkernel::MkRuntimeC::getRT__null_allow (MkRuntimeC *clsHdl)
	return LibMsgqueObject from current MkRuntimeC pointer
static MK_RTN	ccmkkernel::MkRuntimeC::getRTN (const MkRuntimeC *clsHdl)
	(const) return LibMsgqueObject from current MkRuntimeC pointer
static MK_RTN	ccmkkernel::MkRuntimeC::getRTN__null_allow (const MkRuntimeC *clsHdl)
	(const) return LibMsgqueObject from current MkRuntimeC pointer
static MK_RT	ccmkkernel::MkRuntimeC::getRT (const MkRuntimeC &clsHdl)
	return LibMsgqueObject from current MkRuntimeC reference
static MK_RT	ccmkkernel::MkRuntimeC::getRT__null_allow (const MkRuntimeC &clsHdl)
	return LibMsgqueObject from current MkRuntimeC reference
static MK_RTN	ccmkkernel::MkRuntimeC::getRTN (const MkRuntimeC &clsHdl)
	(const) return LibMsgqueObject from current MkRuntimeC reference
static MK_RTN	ccmkkernel::MkRuntimeC::getRTN__null_allow (const MkRuntimeC &clsHdl)
	(const) return LibMsgqueObject from current MkRuntimeC reference
bool	ccmkkernel::MkRuntimeC::Check () const
	check if pointer is still valid

Variables
static thread_local MkRuntimeC	ccmkkernel::MkRuntimeC::MK_NULL_REF = {(MK_OBJ)0}

Detailed Description

MkRuntimeC - The class known as mkrt or runtime is the main ccmkkernel 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 = libmkkernel::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 ccmkkernel 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 libmkkernel::MkSetup and destroyed at MkCleanup.
The runtime-enabled-function always get the runtime-default as first argument in a doc_mk_cc_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 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_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

Function Documentation

Check()

bool ccmkkernel::MkRuntimeC::Check ( ) const

inline

check if pointer is still valid

Definition at line 152 of file MkRuntimeC_cc.hh.

                         {
        return (hdl && MkRtCheck(hdl));
      };

getRT() [1/3]

MK_RT ccmkkernel::MkRuntimeC::getRT ( ) const

inline

return the LibMsgqueObject from current MkRuntimeC instance

Definition at line 84 of file MkRuntimeC_cc.hh.

                          {
        MK_RT ret = reinterpret_cast<MK_RT>(hdl);
        if (unlikely(ret == NULL)) InstHdlIsNullError();
        return ret;
      };

Here is the caller graph for this function:

getRT() [2/3]

static MK_RT ccmkkernel::MkRuntimeC::getRT ( const MkRuntimeC & clsHdl )

inlinestatic

return LibMsgqueObject from current MkRuntimeC reference

Definition at line 132 of file MkRuntimeC_cc.hh.

                                                   {
        return clsHdl.getRT();
      };

getRT() [3/3]

static MK_RT ccmkkernel::MkRuntimeC::getRT ( MkRuntimeC * clsHdl )

inlinestatic

return LibMsgqueObject from current MkRuntimeC pointer

Definition at line 108 of file MkRuntimeC_cc.hh.

                                             {
        MK_RT ret = clsHdl ? reinterpret_cast<MK_RT>(clsHdl->hdl) : NULL;
        if (unlikely(ret == NULL)) ClassHdlIsNullError(MkRuntimeC);
        return ret;
      };

getRT__null_allow() [1/3]

MK_RT ccmkkernel::MkRuntimeC::getRT__null_allow ( ) const

inline

return the LibMsgqueObject from current MkRuntimeC instance

Definition at line 91 of file MkRuntimeC_cc.hh.

                                      {
        return reinterpret_cast<MK_RT>(hdl);
      };

Here is the caller graph for this function:

getRT__null_allow() [2/3]

static MK_RT ccmkkernel::MkRuntimeC::getRT__null_allow ( const MkRuntimeC & clsHdl )

inlinestatic

return LibMsgqueObject from current MkRuntimeC reference

Definition at line 137 of file MkRuntimeC_cc.hh.

                                                               {
        return clsHdl.getRT__null_allow();
      };

getRT__null_allow() [3/3]

static MK_RT ccmkkernel::MkRuntimeC::getRT__null_allow ( MkRuntimeC * clsHdl )

inlinestatic

return LibMsgqueObject from current MkRuntimeC pointer

Definition at line 115 of file MkRuntimeC_cc.hh.

                                                         {
        return clsHdl ? reinterpret_cast<MK_RT>(clsHdl->hdl) : NULL;
      };

getRTN() [1/3]

MK_RTN ccmkkernel::MkRuntimeC::getRTN ( ) const

inline

(const) return the LibMsgqueObject from current MkRuntimeC instance

Definition at line 96 of file MkRuntimeC_cc.hh.

                            {
        MK_RTN ret = reinterpret_cast<MK_RTN>(hdl);
        if (unlikely(ret == NULL)) InstHdlIsNullError();
        return ret;
      };

Here is the caller graph for this function:

getRTN() [2/3]

static MK_RTN ccmkkernel::MkRuntimeC::getRTN ( const MkRuntimeC & clsHdl )

inlinestatic

(const) return LibMsgqueObject from current MkRuntimeC reference

Definition at line 142 of file MkRuntimeC_cc.hh.

                                                     {
        return clsHdl.getRTN();
      };

getRTN() [3/3]

static MK_RTN ccmkkernel::MkRuntimeC::getRTN ( const MkRuntimeC * clsHdl )

inlinestatic

(const) return LibMsgqueObject from current MkRuntimeC pointer

Definition at line 120 of file MkRuntimeC_cc.hh.

                                                     {
        MK_RTN ret = clsHdl ? reinterpret_cast<MK_RTN>(clsHdl->hdl) : NULL;
        if (unlikely(ret == NULL)) ClassHdlIsNullError(MkRuntimeC);
        return ret;
      };

getRTN__null_allow() [1/3]

MK_RTN ccmkkernel::MkRuntimeC::getRTN__null_allow ( ) const

inline

(const) return the LibMsgqueObject from current MkRuntimeC instance

Definition at line 103 of file MkRuntimeC_cc.hh.

                                        {
        return reinterpret_cast<MK_RTN>(hdl);
      };

Here is the caller graph for this function:

getRTN__null_allow() [2/3]

static MK_RTN ccmkkernel::MkRuntimeC::getRTN__null_allow ( const MkRuntimeC & clsHdl )

inlinestatic

(const) return LibMsgqueObject from current MkRuntimeC reference

Definition at line 147 of file MkRuntimeC_cc.hh.

                                                                 {
        return clsHdl.getRTN__null_allow();
      };

getRTN__null_allow() [3/3]

static MK_RTN ccmkkernel::MkRuntimeC::getRTN__null_allow ( const MkRuntimeC * clsHdl )

inlinestatic

(const) return LibMsgqueObject from current MkRuntimeC pointer

Definition at line 127 of file MkRuntimeC_cc.hh.

                                                                 {
        return clsHdl ? reinterpret_cast<MK_RTN>(clsHdl->hdl) : NULL;
      };

MkRuntimeC()

ccmkkernel::MkRuntimeC::MkRuntimeC ( MK_RT hdl )

inline

Definition at line 75 of file MkRuntimeC_cc.hh.

: MkObjectC(MkRuntimeC_X2obj(hdl)) {};

MkRuntimeC_ObjNew()

static MkRuntimeC * ccmkkernel::MkRuntimeC::MkRuntimeC_ObjNew ( MK_RT_ARGS MK_RT hdl )

inlinestatic

return MkRuntimeC from LibMsgqueObject

Definition at line 79 of file MkRuntimeC_cc.hh.

                                                                  {
        return (hdl ? static_cast<MkRuntimeC*>(MkObjectC::atomObjNew(MK_RT_CALL MkRuntimeC_X2obj(hdl))) : &MK_NULL_REF);
      }

Variable Documentation

MK_NULL_REF

thread_local MkRuntimeC ccmkkernel::MkRuntimeC::MK_NULL_REF = {(MK_OBJ)0}

static

Definition at line 36 of file MkRuntimeC_cc.hh.