ccmkkernel

A library that adds an object layer with language bindings to the C language.

SYNOPSIS

The ccmkkernel package is the implementation of the Programming-Language-Micro-Kernel (PLMK) into the target-language C++.

• link: `-Lpath -lccmkkernel` or automake: `LDADD = libccmkkernel.la` 

The ccmkkernel package is a composition of multiple classes defining the Programming-Language-Micro-Kernel (PLMK) :

object	description
ccmkkernel	the namespace with all ccmkkernel specific definitions
ccmkkernel::Attribute	the interface to access the package specific attribute
ccmkkernel::MkClassC.Attribute	the interface to access the class specific attribute
Instance.Attribute	the interface to access the instance specific attribute

To access all features without ccmkkernel prefix use:

• #include LibMkKernel_cc.h
   
   using namespace ccmkkernel; 

Using the ccmkkernel package ...

C++ package libraries

libccmkkernel.so

A shared library or shared object is a computer file that contains executable code designed to be used by multiple computer programs or other libraries at runtime.

libccmkkernel.la

A .la file is a text file used by the GNU libtools package to describe the files that make up the corresponding library.

automake project

Using automake/libtool the ccmkkernel library have to be linked with the executable/library, this is done with:

> LDADD = path/to/libccmkkernel.la

or

> mylib_la_LIBADD = path/to/libccmkkernel.la

Example from example/cc/Makefile.am using libccmqmsgque.la (also load libccmkkernel.la and others)

noinst_PROGRAMS         +=  LcConfigServer
LcConfigServer_SOURCES  =   LcConfigServer.cc
LcConfigServer_CPPFLAGS =   $(CPPFLAGS_mqmsgque)  $(CPPFLAGS_lcconfig)
LcConfigServer_CXXFLAGS =   $(CXXFLAGS_mqmsgque)  -DMETA_IGNORE_EXTERN
LcConfigServer_LDFLAGS  =   $(LDFLAGS_mqmsgque)
LcConfigServer_LDADD    =   $(LIBADD_mqmsgque)    $(LIBADD_lcconfig)

---

TABLE OF CONTENTS

BASICS

Philosophy , Package , ManagedObject , PrimitiveTypes , StorageManagement ,

CLASS

MkKernel PACKAGE , MkObjectC , MkBufferC , MkBufferStreamC , MkBufferListC , MkLogFileC , MkErrorC , MkRuntimeC

MISC

BinaryObject, Examples

INTRODUCTION

C-API: MK_C_API -

The LibMkKernel API …

PHILOSOPHY

theKernel is an infrastructure that link an library-item with a Target-Programming-Language (TPL) using the Programming-Language-Micro-Kernel (PLMK) object-interface. The goal is a programming language independent interface between a C library and the Target-Programming-Language (TPL).

Philosophy

Write Once → Run Everywhere

The library-item is a c-api for a library available as c-header-file.
The library-item is mapped into a Target-Programming-Language (TPL) using a language that is supported by the Programming-Language-Micro-Kernel (PLMK).
Supported Languages are: (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO)

Strategy

It takes 4 years to write a programming-language, but it only takes 4 weeks to insert a micro-kernel.

The library-item is connected to the Target-Programming-Language (TPL) using an api-layer generated by the token-stream-compiler of the Programming-Language-Micro-Kernel (PLMK).

Conclusion

theKernel is used to manage a collection of library-items using an API that is available in all major programming-languages.

PROGRAMMING

The Programming-Language-Micro-Kernel (PLMK) is separted into three programming-layers:

1. The library-layer, used by the theKernel library programmer
2. The tool-layer, used by the theCompiler tool programmer
3. The target-layer, used by the target-language programmer

library-layer

The library-layer implement the ccmkkernel library and is responsible for the quality-target of the entire project.

• implementation of the managed-object technology
  • providing basic classes for: buffer, list, stream, logging, runtime and error
• establishing and managing the library-items
  • providing the startup and cleanup API
  • providing the logging, debugging and error API
  • providing the memory and garbage-collection API
• written in plain C

tool-layer

The tool-layer creates the tools and is responsible for the integration of all components into the NHI1 framework.

• implementation of the project and build technology.
• implementation of the token-stream-compiler technology
• generate the source-code for the target-layer.
• written in plain C, TCL and the Target-Programming-Language (TPL)

target-layer

The target-layer is the API used by the target-language-programmer.

• written in plain Target-Programming-Language (TPL)

Target

!! This documentation describe the implementation-layer and target the C++ programmer. !!

PACKAGE

C-API: MkKernel_C_API - MkKernel PACKAGE - The package is the toplevel structure of the Programming-Language-Micro-Kernel (PLMK) …

The ccmkkernel package is loaded with:

‍

link: `-Lpath -lccmkkernel` or automake: `LDADD = libccmkkernel.la` 

and is a composition of one or more class-item.

The ccmkkernel package add the following public classes into MkObjectC_C_API :

Object	C-Type	Description
MkObjectC	libmkkernel::MK_OBJ	MkObjectC - class known as obj or object is used as base-class type for a Programming-Language-Micro-Kernel (PLMK) class …
MkBufferC	libmkkernel::MK_BUF	MkBufferC - the abstract class known as buf or buffer is used to create and manage dynamic, generic, mixed typed data. …
MkBufferStreamC	libmkkernel::MK_BUS	MkBufferStreamC - the abstract class known as bus or stream is a subclass of MkBufferC and is used for package-based-io …
MkBufferListC	libmkkernel::MK_BFL	MkBufferListC - the class known as bfl or buffer-list is used to create and manage a list of MkBufferC …
MkLogFileC	libmkkernel::MK_LFL	MkLogFileC - the class known as lfl or log-file is used to control the target of the logging-output …
MkErrorC	libmkkernel::MK_ERR	MkErrorC - the class known as err or error is used to create and manage an error message …
MkRuntimeC	libmkkernel::MK_RT	MkRuntimeC - The class known as mkrt or runtime is the main ccmkkernel application environment …

The ccmkkernel package add the following public types into MkObjectC_C_API :

    ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType)
    |
    |- ABSTRACT: MkSuperTypeSTT (TypeType = type of a Type)
       |
       |- MkObjectST, MkLogFileST, MkBufferListST,
       |- MkErrorPanicST, MkErrorIgnoreST, MkErrorPrintST, MkErrorDefaultST, MkErrorST
       |
       |- ABSTRACT: MkBufferST
          |- FINAL: MkBuffer64ST, MkBuffer256ST, MkBuffer1024ST
          |- ABSTRACT: MkBufferStreamST
             | FINAL: MkBufferStream64ST, MkBufferStream256ST, MkBufferStream1024ST, MkBufferStream16384ST

MANAGED OBJECT

C-API: MkObjectC_C_API - MkObjectC - class known as obj or object is used as base-class type for a Programming-Language-Micro-Kernel (PLMK) class …

ccmkkernel is also called as Programming-Language-Micro-Kernel (PLMK). ccmkkernel is like a programming-language without syntax but using the Target-Programming-Language (in our case C++) of the Micro-Kernel as runtime environment.

Integration

To operate as a Micro-Kernel a maximum integration into the Target-Programming-Language is available.

This integration is done using the managed-object-technology.

Managed-Object

A managed-object is a piece of C-Code able to act as a native datatype in all Target-Programming-Languages supported.

The managed object supports low level integration features descripted in MkObjectS :

• object identification based on signatures
• reference counting
• management of the self object pointer for the target-language
• object-type specific features provided with MkTypeS

In the implementation-layer of ccmkkernel only the public-features of the MkObjectC are visible to the programmer.

See also

For the full documentation read: Managed-Object

PRIMITIVE TYPE

C-API: MkKernel_PrimitiveType_C_API - MkKernel PACKAGE - a collection of all native-data-types supported by MkBufferC …

The data send from one package-item to an other package-item is focused on speed and usability. By default the data is send as binary, only if the endian changes or a string representation is required an additional transformation is done.
The data send from one package-item to an other package-item is limited to a collection of specific types, based on native C data types.
An ccmkkernel-API command with a focus on a specific type is using a type-postfix, for example MqReadSTR read a (STR=string) data from the read-package.
In the documentation the type-item (TT) is a synonym for a (Y,O,S,I,W,F,D,B,C,L,U) type-item.

The following native-type identifier are available:

TT	T	native	comment
BOL	O	MK_BOL	1 byte boolean value using true or false
I8	Y	MK_I8	1 byte signed character
I16	S	MK_I16	2 byte signed short
I32	I	MK_I32	4 byte signed integer
I64	W	MK_I64	8 byte signed long long integer
FLT	F	MK_FLT	4 byte float
DBL	D	MK_DBL	8 byte double
BIN	B	MK_BINN	unsigned char array used for binary data
STR	C	MK_STR	string data using a \0 at the end

The following composee identifier's are available:

TT	T	native	comment
BUF	U	MkBufferC*	buffer-item that can hold any single typed item from above
BFL	L	MkBufferListC*	buffer-list that can hold many buffer-item from above

Every native-data-type is encapsualted into a MkBufferC. A MkBufferC is type safe, this mean that every read to a MkBufferC have to match the data-type of the previous write. One exception is available, the cast from and to the C data-type (TYPE=C) is allowed.

Sending data mean sending one ore more MkBufferC from one package-item to an other package-item. The sender is using a MqSendTT command to put data as MkBufferC into an send-data-package and the reveiver is using a MqReadTT command to retrieve the data from the read-data-package.

POINTER TYPE

C-API: MkKernel_PointerType_C_API - MkKernel PACKAGE - a collection of types allocates as array of data and supported by MkBufferC …

For native type support read: MkKernel_PrimitiveType_C_API

The pointer-type is part of the native-type and usually support the size argument to propper allocate storage.

The following pointer-type identifier is available in MkBufferS:

TT	T	type	const type	comment
BIN	B	libmkkernel::MK_BIN	libmkkernel::MK_BINN	byte-array pointer data-type with binary encoding (MK_BINN)
STR	C	libmkkernel::MK_STR	libmkkernel::MK_STRN	string pointer data-type with UTF8 ecoding (MK_STR)

STORAGE MANAGEMENT

C-API: MkKernel_Storage_C_API - MkKernel PACKAGE - Storage Management …

Storage management is used in ccmkkernel to provide temporary storage. It is a common design pattern that ccmkkernel only returns a reference to the Internal-Temporary-Storage (ITS), so the Internal-Active-Storage (IAS) is not returned to the external end user. The ITS is a storage that is only used as a return value and nothing else. The temporary in ITS refers exclusively to the current state of the storage and not to the lifespan of the storage, the ITS is only allocated once at startup and then used again and again, similar to the static storage in C.

Internal ccmkkernel distinguishes three different storage sources:

Context-Local-Storage (CLS)

CLS is tied to a specific MqContextC.
Example: the MqReadBUF returns a reference to an internal MkBufferC.

Funktion-Local-Storage (FLS)

FLS is used as the local temporary storage, usually as thread-local-storage, of a function-return-value.
Example: the MqReadBFL returns a MkBufferListC which is filled with multiple MkBufferC.

Runtime-Local-Storage (RLS)

RLS is used as global thread-local-storage per RunTime instance.
Example: the MkErrorC only exists ONCE per runtime.

The CLS and FLS have the same visibility to the end user and are explained together as FLS.
The RLS is not mentioned in this documentation section because the RLS is more internal than CLS and FLS.

The end-user uses a FLS reference like a normal local C++ variable but with the following restriction:

1. The value of the variable is a reference to the FLS storage belonging to the method that returned the reference.
2. A FLS storage only ever exists once in a thread, which means that the FLS storage of a reference is overwritten if the FLS storage is used a second time in the same context.
3. A context is, for example, a coherent block of code such as in a "service callback". A coherent context is broken if the same method that returned the original FLS as a result is called a second time or if a method is called that uses the "event loop".
4. FLS storage must NOT be released by the end user, the Programming-Language-Micro-Kernel (PLMK) always ensures that the storage management of ccmkkernel and the target-language is synchronized.
5. If a FLS reference is added to another reference and this reference is also managed by the Programming-Language-Micro-Kernel (PLMK), the Programming-Language-Micro-Kernel (PLMK) automatically ensures that the storage management is coherent, which means that the end user does not have to do anything.
6. The FLS reference can be updated. This means that the FLS storage is being updated because the reference owner (usually a local variable) temporarily owns the FLS storage.

The "Dup" (duplicate) function is used to convert a temporary FLS variable into a global storage. The global storage is managed by the end user and may have to be released depending on the target programming language.

Example from server.cc → ReadBFL overwrite previous ReadBFL

      void BFL2() {
        auto tmp1 = ReadBFL()                     ; // "tmp1" is now a reference to the FLS storage of "ReadBFL"
        auto tmp2 = ReadBFL()                     ; // ERROR: the "tmp2" is using a SHARED reference with "tmp1"
        Send("R","LL",tmp1,tmp2)                  ; // ERROR: "tmp1" and "tmp2" are the SAME values
      }

Example from server.cc → ReadBFL overwrite previous ReadBFL even in an Event-Loop

      void pBFL3() {
        /* tmp2 = */ ReadBFL()                    ; // ERROR: the "tmp2" is using a SHARED reference with "tmp1"
      }
      void BFL3() {
        auto tmp1 = ReadBFL()                     ; // "tmp1" is now a reference to the FLS storage of "ReadBFL"
        Send("C",MqTokenICB(&Server::pBFL3),"ECOL:[III]",4,5,6)      ; // ATTENTION: callback "pBFL3" using "ReadBFL"
        ProcessEvent(MQ_WAIT_OWN)                 ; // ERROR: enter event-loop, callback "pBFL3" is called
        Send("R","L",tmp1)                        ; // ERROR: "tmp1" has now the value from "tmp2"
      }

Example from server.cc → convert ReadBFL result into global storage using Dup and free later

      void BFL4() {
        auto tmp1 = ReadBFL()                     ; // "tmp1" is now a reference to the FLS storage of "ReadBFL"
        auto glb1 = tmp1->Dup()                   ; // OK: "glb1" is now a UNSHARED reference to the global memory
        auto tmp2 = ReadBFL()                     ; // "tmp2" is now a reference to the FLS storage of "ReadBFL"
        Send("R","LL",glb1,tmp2)                  ; // OK: "glb1" (alias tmp1) and "tmp2" are separate references
        glb1->Delete()                            ; // without "garbage-collection" the global memory must be released
      }

Thread-Local-Storage (TLS) used by the *CreateTLS style of functions

In the C language the TLS (Thread-Local-Storage) is unique per definition and the name is used to distinguish the storage.

‍The Problem is to create a TLS interface useable in all Target-Programming-Language (TPL) supported by the Programming-Language-Micro-Kernel (PLMK).

The *CreateTLS style function return a TLS that is a global storage. global mean unique per runtime and not unique per definition. The string tlsid is used to distinguish the storage on the global level.

‍Every *CreateTLS style function with the same tlsid return the same memory in the same thread.

There is always a risk that the memory used by the *CreateTLS style of functions will also be used by another component of the software in the same thread.

Attention

• Use the *CreateTLS style function with caution in a local (controlled) context.
• It is a good-practice to manage the tlsid on a global level like an enum
• If the tlsid is not managed, it will be a problem when the event-loop is invoked or an asynchronous-service-call is received or made and other code uses the same tlsid

Example from perfserver.cc → performance test with TLS storage in a local (controlled) context

    void BUST () {
      auto bus = MkBufferStreamC::CreateTLS( "perfserver-BUST" );
      while (ReadItemExists()) {
        bus->WriteBUF(ReadBUF());
      }
      bus->PosToStart();
      SendSTART();
      while (bus->ReadItemExists()) {
        SendBUF(bus->ReadBUF());
      }
      SendRETURN();
    }

Example from LibSq3LiteRpcClient.tcl → callback dealing the temporary TLS data

# Intro     : Example from tcl-rpc-client of using a CreateTLS-like function (here for MkBufferListC) 
#             to improve code speed and readability.
#
# Problem   : This function is used to invoke a callback (myCb). The arguments come from the argument 
#             list args *and* from a service call (ReadBFL).
#             The problem is that ReadBFL is called *twice* and the *second* call overwrites the value 
#             of the *first* call because CreateTLS always returns *the same* MkBufferListC, just 
#             replaced with a new set of values.
#
# Solution  : The MkBufferListC instance returned by ReadBFL is copied into another MkBufferListC 
#             instance returned by CreateTLS.
#             The "CreateTLS" instance is only created *once* and reused, *but* now we can create as 
#             many MkBufferListC instances as we want, because "CreateTLS" distinguishes the returned 
#             instances by the string identifier. 
#             WITHOUT "CreateTLS" a copy would have to be created (Dup) which would then be destroyed 
#             *after* the callback is called (Delete)

proc Sq3LiteRpcClientExecV2CB {rpc myCb args} {
  set valL [MkBufferListC CreateTLS "Sq3LiteRpcClientExecV2CB→valL"]
  set colL [MkBufferListC CreateTLS "Sq3LiteRpcClientExecV2CB→colL"]

  $valL Copy [$rpc ReadBFL]
  $colL Copy [$rpc ReadBFL]

  $myCb {*}$args $valL $colL
}

---

MkKernel PACKAGE

MkKernel SETUP			MkKernel PACKAGE - Setup und Cleanup the ccmkkernel …
MkKernel ENUM
		enum libmkkernel::MkTypeE	basic data-types supported by Programming-Language-Micro-Kernel (PLMK) …
		enum libmkkernel::MkTimeoutE	Predefined Timeout values …
		enum libmkkernel::MkIdSE	signal type of the MkIdS data val …
		enum libmkkernel::MkErrorE	collection for the different error-codes …

MkKernel DETAIL

C-API: MkKernel_C_API - MkKernel PACKAGE - The package is the toplevel structure of the Programming-Language-Micro-Kernel (PLMK) …

The ccmkkernel package is loaded with:

‍

link: `-Lpath -lccmkkernel` or automake: `LDADD = libccmkkernel.la` 

and is a composition of one or more class-item.

The ccmkkernel package add the following public classes into MkObjectC_C_API :

Object	C-Type	Description
MkObjectC	libmkkernel::MK_OBJ	MkObjectC - class known as obj or object is used as base-class type for a Programming-Language-Micro-Kernel (PLMK) class …
MkBufferC	libmkkernel::MK_BUF	MkBufferC - the abstract class known as buf or buffer is used to create and manage dynamic, generic, mixed typed data. …
MkBufferStreamC	libmkkernel::MK_BUS	MkBufferStreamC - the abstract class known as bus or stream is a subclass of MkBufferC and is used for package-based-io …
MkBufferListC	libmkkernel::MK_BFL	MkBufferListC - the class known as bfl or buffer-list is used to create and manage a list of MkBufferC …
MkLogFileC	libmkkernel::MK_LFL	MkLogFileC - the class known as lfl or log-file is used to control the target of the logging-output …
MkErrorC	libmkkernel::MK_ERR	MkErrorC - the class known as err or error is used to create and manage an error message …
MkRuntimeC	libmkkernel::MK_RT	MkRuntimeC - The class known as mkrt or runtime is the main ccmkkernel application environment …

The ccmkkernel package add the following public types into MkObjectC_C_API :

    ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType)
    |
    |- ABSTRACT: MkSuperTypeSTT (TypeType = type of a Type)
       |
       |- MkObjectST, MkLogFileST, MkBufferListST,
       |- MkErrorPanicST, MkErrorIgnoreST, MkErrorPrintST, MkErrorDefaultST, MkErrorST
       |
       |- ABSTRACT: MkBufferST
          |- FINAL: MkBuffer64ST, MkBuffer256ST, MkBuffer1024ST
          |- ABSTRACT: MkBufferStreamST
             | FINAL: MkBufferStream64ST, MkBufferStream256ST, MkBufferStream1024ST, MkBufferStream16384ST

MkKernel SETUP

NAVI: top, up

		Cleanup	cleanup ccmkkernel internal memory …
		Setup	setup ccmkkernel internal memory …

MkKernel SETUP DETAILS

C-API: MkKernel_Setup_libmkkernel_C_API - MkKernel PACKAGE - Setup und Cleanup the ccmkkernel …

Initializing a ccmkkernel library depends on the Target-Programming-Language (TPL) and the specific nature of the Programming-Language-Micro-Kernel (PLMK).

In general it is required to call a Setup style funtion as FIRST command because of:

• In a static build the shared library constructor/destructor is NOT called
• In a shared build the order of library loading is target-language-specific
• Every executable who uses a meta-library (MkKernel, MqMsgque, LcConfig, ...) which provide a language-specific-type (always assume this) and also support static-build (no constructor is called like C, C++, ...) require a call to the meta-library-setup-function for type-initialization at startup.

If more than one META library is called only the toplevel Setup is required:

• example: The MkKernelSetup is not required if MqMsgqueSetup or LcConfigSetup is already used.

shared library detail

A new ccmkkernel library is initialized with Setup and released again with Cleanup. Both functions are automatically called upon loading and unloading of the shared library.

Example: Definition (C) of the ccmkkernel library startup functions

MK_EXTERN void MK_DECL MkSetup (void) __attribute__ ((constructor(200)));
MK_EXTERN void MK_DECL MkCleanup (void) __attribute__ ((destructor(200)));

In the Programming-Language-Micro-Kernel (PLMK), a type is defined for each thread, which means that the new ccmkkernel library must be known when the thread starts. This is not a problem as long as the external ccmkkernel library is linked to the application. However, if dlopen is used to load the ccmkkernel library, the current restriction is that the new data type from the ccmkkernel library has not been defined in all existing threads.

The point in time when a library is loaded depends heavily on the programming language used.

• A linked language such as C or C++ usually has all libraries initialised at startup.
• A compiled language such as Java and C# only load a library when a function of the library is used and not when the library is declared.
• A scripting language such as Tcl normally loads the library as soon as the declaration (package require myLib) is made, which happens fairly close to the start of the program but is not guaranteed.

‍To avoid all the problems call the Setup directly at the start of the main program.

Example: Start of the LcConfigServer application from the example/cs directory

• The problem with the LcConfigServer application is that the libmkkernel and libmqmsgque libraries are loaded very early, at startup, and the liblcconfig very late, only on request.

static void Main(string[] argv) {
 
  LcConfig.Setup();
 
  var srv = MqFactoryCT<LcConfigServer>.Add().New();
 
  try {
    srv.LinkCreate(argv);
    srv.ProcessEvent(MqWaitOnEventE.FOREVER);
  } catch (Exception e) {
    srv.ErrorCatch(e);
  }
  srv.Exit();
}

[static] MkKernel::Cleanup()

top cleanup ccmkkernel internal memory … → API: ccmkkernel::MkKernel::Cleanup

MkCleanup will only be recognized once and will be ignored if not called in the same thread as MkSetup. After a call to MkSetup the call to MkCleanup is possible again.

‍The public MkCleanup is just a placeholder, the internal MkCleanup is always called even if the public MkCleanup is not called.

Attention

during cleanup objects will be deleted too -> the language interpreter have to be active

[static] MkKernel::Setup()

top setup ccmkkernel internal memory … → API: ccmkkernel::MkKernel::Setup

MkSetup will only be recognized once, additional call's will be ignored until a MkCleanup is called.

‍A call to the public MkSetup is required if dlopen and thread is used.

MkKernel ENUM

C-API: MkKernel_Enum_C_API - MkKernel PACKAGE - enum definition …

A enum in the Programming-Language-Micro-Kernel (PLMK) is a enum-data-type and 3 enum-access-attributes

1. ENUM_ToString → return the string-value from the enum-value
2. ENUM_ToInt → return the integer-value from the enum-value
3. ENUM_FromInt → create an enum-value from an integer-value.

The enum-data-type and the 3 enum-access-attributes are defined in all target-languages (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO).

enum libmkkernel::MkErrorE

top collection for the different error-codes … → API: libmkkernel::MkErrorE

This is the default-error-indicator and the return-value from near all Programming-Language-Micro-Kernel (PLMK) functions.

enum MkErrorE {
  MK_OK         = 0,            
  MK_CONTINUE   = 1,            
  MK_ERROR      = 2,            
};

[static] MkErrorE MkKernel::ErrorE_FromInt(MK_I32 value)

top return the MkErrorE from integer … → API: ccmkkernel::MkKernel::ErrorE_FromInt

[static] MK_I32 MkKernel::ErrorE_ToInt(MkErrorE value)

top return the MkErrorE as integer … → API: ccmkkernel::MkKernel::ErrorE_ToInt

[static] MK_STRN MkKernel::ErrorE_ToString(MkErrorE value)

top return the MkErrorE as string … → API: ccmkkernel::MkKernel::ErrorE_ToString

enum libmkkernel::MkIdSE

top signal type of the MkIdS data val … → API: libmkkernel::MkIdSE

[static] MkIdSE MkKernel::IdSE_FromInt(MK_I32 value)

top return the MkIdSE from integer … → API: ccmkkernel::MkKernel::IdSE_FromInt

[static] MK_I32 MkKernel::IdSE_ToInt(MkIdSE value)

top return the MkIdSE as integer … → API: ccmkkernel::MkKernel::IdSE_ToInt

[static] MK_STRN MkKernel::IdSE_ToString(MkIdSE value)

top return the MkIdSE as string … → API: ccmkkernel::MkKernel::IdSE_ToString

enum libmkkernel::MkTimeoutE

top Predefined Timeout values … → API: libmkkernel::MkTimeoutE

The libmkkernel::MkTimeoutE is used wherever a "timeout" is required. As a special feature, in addition to the defined values in libmkkernel::MkTimeoutE, freely defined values as integers as seconds are also accepted.

__parser__(enum-accept-integer=long)
enum MkTimeoutE {
  MK_TIMEOUT_INIT       = META_TIMEOUT_REF,
  MK_TIMEOUT_LONG       = (META_TIMEOUT_REF/5),
  MK_TIMEOUT_NORMAL     = (META_TIMEOUT_REF/10  < 1 ? 1 : META_TIMEOUT_REF/10),
  MK_TIMEOUT_SHORT      = (META_TIMEOUT_REF/45  < 1 ? 1 : META_TIMEOUT_REF/45),
  MK_TIMEOUT_SOCKET     = (META_TIMEOUT_REF/90  < 1 ? 1 : META_TIMEOUT_REF/90),
  MK_TIMEOUT_VERYSHORT  = (META_TIMEOUT_REF/180 < 1 ? 1 : META_TIMEOUT_REF/180),
  MK_TIMEOUT_DEFAULT    = -1,
  MK_TIMEOUT_USER       = -2,
  MK_TIMEOUT_MAX        = -3,
};

[static] MkTimeoutE MkKernel::TimeoutE_FromInt(MK_I32 value)

top return the MkTimeoutE from integer … → API: ccmkkernel::MkKernel::TimeoutE_FromInt

[static] MK_I32 MkKernel::TimeoutE_ToInt(MkTimeoutE value)

top return the MkTimeoutE as integer … → API: ccmkkernel::MkKernel::TimeoutE_ToInt

[static] MK_STRN MkKernel::TimeoutE_ToString(MkTimeoutE value)

top return the MkTimeoutE as string … → API: ccmkkernel::MkKernel::TimeoutE_ToString

enum libmkkernel::MkTypeE

top basic data-types supported by Programming-Language-Micro-Kernel (PLMK) … → API: libmkkernel::MkTypeE

enum MkTypeE {
  MK_I8T  = ((1  <<  MK_TYPE_SHIFT) | MK_TYPE_IS_1_I8E ),  
  MK_BOLT = ((2  <<  MK_TYPE_SHIFT) | MK_TYPE_IS_1_I8E ),  
  MK_I16T = ((3  <<  MK_TYPE_SHIFT) | MK_TYPE_IS_2_I8E ),  
  MK_I32T = ((4  <<  MK_TYPE_SHIFT) | MK_TYPE_IS_4_I8E ),  
  MK_FLTT = ((5  <<  MK_TYPE_SHIFT) | MK_TYPE_IS_4_I8E ),  
  MK_I64T = ((6  <<  MK_TYPE_SHIFT) | MK_TYPE_IS_8_I8E ),  
  MK_DBLT = ((7  <<  MK_TYPE_SHIFT) | MK_TYPE_IS_8_I8E ),  
  MK_BINT = ((8  <<  MK_TYPE_SHIFT)                     ),  
  MK_STRT = ((9  <<  MK_TYPE_SHIFT)                     ),  
  MK_LSTT = ((10 <<  MK_TYPE_SHIFT)                     ),  
};

See also

MkTypeE_ToString, MkTypeE_ToInt, MkTypeE_FromInt, BufferGetType2, BufferCastTo, BufferStreamReadGetNextType

[static] MkTypeE MkKernel::TypeE_FromInt(MK_I32 value)

top return the MkTypeE from integer … → API: ccmkkernel::MkKernel::TypeE_FromInt

[static] MK_I32 MkKernel::TypeE_ToInt(MkTypeE value)

top return the MkTypeE as integer … → API: ccmkkernel::MkKernel::TypeE_ToInt

[static] MK_STRN MkKernel::TypeE_ToString(MkTypeE value)

top return the MkTypeE as string … → API: ccmkkernel::MkKernel::TypeE_ToString

---

MkObjectC

MkObjectC CLASS
		Export	MkObjectC - Export class functions …
		Introspection	MkObjectC - Introspection class functions …
		Misc	MkObjectC - Misc class functions …
MkObjectC TOR
		DeleteCallbackCleanup	cleanup the DeleteCallback installed with MkObjectDeleteCallbackSetup …
		DeleteCallbackSetup	Create/Delete the instance-delete-callback …
		Delete	Delete-Slot - delete an instance.
		Dispose	Dispose-Slot - untie the connection between the Native-C++-Instance and the ccmkkernel-Instance.
MkObjectC DBG
		DbgM	debug: write a static-marker to the MkLogFileC (default: stderr) …
		DbgDump	debug: Dump a instance to stderr with LNG and MQ internal data…
		DbgL	debug: write a instance-marker to the MkLogFileC (default: stderr) using the fmtobj as prefix …
		DbgLogC	debug: write a short-obj-summary to MkLogFileC (default: stderr) …
		DbgO	debug: write the object-details to MkLogFileC (default: stderr) …
		DbgSTACK	debug: write the stack-trace to MkLogFileC (default: stderr) …
MkObjectC LOG
		LogC	write a logging-message to MkLogFileC (default: stderr) using the internal format …
		LogHEX	log binaray data as HEX into the MkLogFileC (default: stderr) …
		LogV	write a printf style logging-message to MkLogFileC (default: stderr) using the internal format …
		LogVL	write a vprintf style logging-message to MkLogFileC using the internal format …
		Log	Log-Slot - log a summary of an object to the MkLogFileC (default: stderr) target …
		LogDetail	log the MkObjectS verbose into the MkLogFileC (default: stderr) …
		LogSimple	log the MkObjectS into the MkLogFileC (default: stderr) …
MkObjectC MISC
		ErrorCatch	convert a programming-language-error into an ccmkkernel error …
		IsNull	ckeck if the object is MK_NULL
		ToError	Error-Slot - return an error-object pre initialized with obj data.
		ToName	Info-Slot - returns brief information about the obj as a string
		ToNameOfClass	Class-Slot - returns the C++-Class-Name of the obj as string
		ToNameOfType	Type-Slot - returns the LibMkKernel-Type-Name of the obj as a string
		ToString	String-Slot - returns the string representation of the inst …

MkObjectC DETAIL

C-API: MkObjectC_C_API - MkObjectC - class known as obj or object is used as base-class type for a Programming-Language-Micro-Kernel (PLMK) class …

ccmkkernel is also called as Programming-Language-Micro-Kernel (PLMK). ccmkkernel is like a programming-language without syntax but using the Target-Programming-Language (in our case C++) of the Micro-Kernel as runtime environment.

Integration

To operate as a Micro-Kernel a maximum integration into the Target-Programming-Language is available.

This integration is done using the managed-object-technology.

Managed-Object

A managed-object is a piece of C-Code able to act as a native datatype in all Target-Programming-Languages supported.

The managed object supports low level integration features descripted in MkObjectS :

• object identification based on signatures
• reference counting
• management of the self object pointer for the target-language
• object-type specific features provided with MkTypeS

In the implementation-layer of ccmkkernel only the public-features of the MkObjectC are visible to the programmer.

See also

For the full documentation read: Managed-Object

MkObjectC CLASS

NAVI: top, up

MkObjectC CLASS EXPORT

		HandleDeleteByNetHdl	Handle-Delete-Slot - delete a netHdl from handle-storage …
		HandleResolve	Handle-Resolve-Slot - return a MkObjectC from netHdl or MK_NULL if invalid…
		HandleDelete	Handle-Delete-Slot - delete a netObj from handle-storage …
		HandleExists	check if obj has already a handle defined…
		HandleGet	Handle-Get-Slot - returns a export-hdl to the MkObjectC useable for external storage
		HandleGetOfType	Export-Slot - returns typeHdl of the obj .
		HandleGetOr0	return export-hdl or 0 in not created…

MkObjectC CLASS INTROSPECTION

		Instances	get head-instance from linked-list of MkObjectS type …
		Next	get next instance from linked-list of MkObjectS type
		Prev	get previous instance from linked-list of MkObjectS type

MkObjectC CLASS MISC

GetNull

Null-Slot - return a MkObjectC typed NULL instance …

MkObjectC CLASS DETAILS

C-API: MkObjectC_Class_C_API - MkObjectC - define the class …

MkObjectC CLASS EXPORT

MkObjectC - Export class functions …

[static] MkObjectC::HandleDeleteByNetHdl(MK_HDL netHdl)

top Handle-Delete-Slot - delete a netHdl from handle-storage … → API: ccmkkernel::MkObjectC::HandleDeleteByNetHdl

[static] MkObjectC* MkObjectC::HandleResolve(MK_HDL netHdl)

top Handle-Resolve-Slot - return a MkObjectC from netHdl or MK_NULL if invalid… → API: ccmkkernel::MkObjectC::HandleResolve

The MkObjectHandleResolve undo the MkObjectHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	netHdl	handle former exported with MkObjectHandleGet

Returns

the required handle or MK_NULL if netHdl is invalid

netObj.HandleDelete()

top Handle-Delete-Slot - delete a netObj from handle-storage … → API: ccmkkernel::MkObjectC::HandleDelete

MK_BOOL obj.HandleExists()

top check if obj has already a handle defined… → API: ccmkkernel::MkObjectC::HandleExists

Parameters

[in]

obj

the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API

Returns

true or false

MK_HDL obj.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkObjectC useable for external storage → API: ccmkkernel::MkObjectC::HandleGet

The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MkObjectHandleResolve.

By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.

The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.

example: The export-hdl is used in rpc to identify an object across the network.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API

Returns

the required export-hdl

MK_HDL obj.HandleGetOfType()

top Export-Slot - returns typeHdl of the obj . → API: ccmkkernel::MkObjectC::HandleGetOfType

A typeHdl identifies the type the obj belongs to. All instances of the same type share the same typeHdl.

Parameters

[in]

obj

the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API

Returns

the required typeHdl

MK_HDL obj.HandleGetOr0()

top return export-hdl or 0 in not created… → API: ccmkkernel::MkObjectC::HandleGetOr0

Same as MkObjectHandleGet, but no new export-hdl is created if it has not already been created and the initial value 0 is returned instead.

Parameters

[in]

obj

the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API

Returns

the required export-hdl

MkObjectC CLASS INTROSPECTION

MkObjectC - Introspection class functions …

[static] MkObjectC* MkObjectC::Instances()

top get head-instance from linked-list of MkObjectS type … → API: ccmkkernel::MkObjectC::Instances

The head-instance is the last instance created.

MkObjectC* obj.Next()

top get next instance from linked-list of MkObjectS type → API: ccmkkernel::MkObjectC::Next

MkObjectC* obj.Prev()

top get previous instance from linked-list of MkObjectS type → API: ccmkkernel::MkObjectC::Prev

MkObjectC CLASS MISC

MkObjectC - Misc class functions …

[static] MkObjectC* MkObjectC::GetNull()

top Null-Slot - return a MkObjectC typed NULL instance … → API: ccmkkernel::MkObjectC::GetNull

MkObjectC TOR

C-API: MkObjectC_TOR_C_API - MkObjectC - create and destroy a managed-object …

[static] MkObjectC::DeleteCallbackCleanup(MK_STRN ident)

top cleanup the DeleteCallback installed with MkObjectDeleteCallbackSetup … → API: ccmkkernel::MkObjectC::DeleteCallbackCleanup

See also

MkObjectDeleteCallbackSetup

[static] MkObjectC::DeleteCallbackSetup(MK_STRN ident, MkObjectDeleteICB MkObjectDeleteCCB MkObjectDeleteSCB callback = NULL, MK_STRN filter = NULL)

top Create/Delete the instance-delete-callback … → API: ccmkkernel::MkObjectC::DeleteCallbackSetup

The callback is called shortly before deleting an instance and is used to synchronize object management across the network.

The ident identifies the callback

• before a new callback is created the existing-callback with name ident is deleted.
• The ident is also required to delete the callback.
• If the special ident ALL is used than all callbacks are deleted first.

The fCall (C-Only) or callback (Non-C) it is the callback called

• If MK_NULL than the callback with name ident is deleted if exists and no new callback is created.
• If MK_NULL then it is identical to MkObjectDeleteCallbackCleanup(ident).

The filter is a POSIX Extended Regular Expression to filter on type-names.

• The filter is optional and is only used if not MK_NULL and not "":
• The filter is applied to MkTypeS::type_name like MkBufferC.
• The POSIX Extended Regular Expression syntax is defined in man 7 regex.
• If the filter is not used, the fCall is called on every instance deletion !

C-callback definition details:

Read more at MkObjectDeleteCallF

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	ident	Identify the callback, have to ne non MK_NULL and not "".
[in]	fCall	(C-Only) Internal required: the callback, if MK_NULL than the callback is deleted.
[in]	callback	Optional: the parameter for fcall, for cleanup use fFree.
[in]	fFree	(C-Only) Internal optional: cleanup callback data
[in]	filter	Optional: is an regular expression to filter for MkTypeS::type_name.

See also

MkObjectDeleteCallbackCleanup

MkObjectDeleteCallbackSetup : overload

 
      void DeleteCallbackSetup (MK_STRN ident, MkObjectDeleteCCB callback = NULL, MK_STRN filter = NULL);
 
      void DeleteCallbackSetup (const std::string& ident, MkObjectDeleteCCB callback = NULL, MK_STRN filter = NULL);
 
      void DeleteCallbackSetup (MK_STRN ident, MkObjectDeleteICB callback = NULL, MK_STRN filter = NULL);
 
      void DeleteCallbackSetup (const std::string& ident, MkObjectDeleteICB callback = NULL, MK_STRN filter = NULL);
 
      static void DeleteCallbackSetup (MK_STRN ident, MkObjectDeleteSCB callback = NULL, MK_STRN filter = NULL);

MkObjectDeleteCallbackSetup : callback signature

Read more at: Callback signature

MkObjectDeleteCallbackSetup : callback example

Read more at: Callback example

[destructor] obj.Delete()

top Delete-Slot - delete an instance. → API: ccmkkernel::MkObjectC::Delete

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. The internal memory will be freed and the object-pointer will be set to NULL. If the object-pointer is already NULL nothing will be done.
2. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
3. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
4. After a SOFT-delete, the outher shell is still alive, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.
5. On HARD-delete read more at MkSelfDeleteForce

[destructor] obj.Dispose()

top Dispose-Slot - untie the connection between the Native-C++-Instance and the ccmkkernel-Instance. → API: ccmkkernel::MkObjectC::Dispose

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
2. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
3. After a SOFT-delete, the outher shell is still active, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.

MkObjectC DBG

C-API: MkObjectC_Dbg_C_API - MkObjectC - log a debugging-message to the MkLogFileC (default: stderr) …

This functions are "helpers" to support the programmer.

[static] MkObjectC::DbgM(MK_STRN message, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top debug: write a static-marker to the MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::DbgM

obj.DbgDump(MK_STRN message = "var", MK_STRN callfunc = __builtin_FUNCTION())

top debug: Dump a instance to stderr with LNG and MQ internal data… → API: ccmkkernel::MkObjectC::DbgDump

Attention

this is only implemented by the Target-Programming-Language (TPL)

fmtobj.DbgL(MK_STRN message, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top debug: write a instance-marker to the MkLogFileC (default: stderr) using the fmtobj as prefix … → API: ccmkkernel::MkObjectC::DbgL

The marker is prefixed with object data from th fmtobj.

obj.DbgLogC(MK_STRN callfunc = __builtin_FUNCTION())

top debug: write a short-obj-summary to MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::DbgLogC

obj.DbgO(MK_STRN callfunc = __builtin_FUNCTION())

top debug: write the object-details to MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::DbgO

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API (MK_NULL allowed)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)

This function can be overwritten in the target programming language.

fmtobj.DbgSTACK(MK_I32 skip = 0, MK_I32 num = -1, MK_STRN callfunc = __builtin_FUNCTION())

top debug: write the stack-trace to MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::DbgSTACK

MkObjectC LOG

C-API: MkObjectC_Log_C_API - MkObjectC - log information to MkLogFileC (default: stderr) …

The logging-target is set direct by RuntimeSetLogfile or using the class MkLogFileC.

The target is stored at the MkRuntimeC using a FILE-stream and can be set individually for each thread. The default is stderr.

• the handle is stored at MkRuntimeS::logFILE
• the filename (if available) is stored at MkRuntimeS::logfile

possible values are:

value	decription	OS man-page
stdout	the standart output	stdio(3)
stderr	the standart error output	stdio(3)
fileName	an arbitary fileName	fopen(3)

Many logging functions have common parameters:

Parameters

[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)

fmtobj.LogC(MK_STRN message, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION())

top write a logging-message to MkLogFileC (default: stderr) using the internal format … → API: ccmkkernel::MkObjectC::LogC

The logging is only done if 'MqDebug >= level' and 'MqIsSilent == false' using the following format:

C> (NAME:PID:THREADID) [YYYY-MM-DD:HH-MM-SS] [String|Binary-DEBUGLEVEL-CONTEXTID-REFCOUNT-CONTEXTPTR-prefix]: message

The message is build with snprintf and finally send with fputsn without newline '\n' character at the end. To add the newline or an other special-caracter use the '\xxx' syntax.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	message	string to log

fmtobj.LogHEX(MK_STRN callfunc, MK_BNP data)

top log binaray data as HEX into the MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::LogHEX

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	data	the binary data to log

fmtobj.LogV(MK_STRN callfunc, MK_DBG debug, MK_FST printfmt, ... )

top write a printf style logging-message to MkLogFileC (default: stderr) using the internal format … → API: ccmkkernel::MkObjectC::LogV

Use the format and the restrictions from LogC.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	printfmt	is a c-string used as printf like format string

fmtobj.LogVL(MK_STRN callfunc, MK_DBG debug, MK_FST printfmt, va_list var_list)

top write a vprintf style logging-message to MkLogFileC using the internal format … → API: ccmkkernel::MkObjectC::LogVL

Use the format and the restrictions from LogC.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	printfmt	is a c-string used as printf like format string
[in]	var_list	a variable argument list object

obj.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top Log-Slot - log a summary of an object to the MkLogFileC (default: stderr) target … → API: ccmkkernel::MkObjectC::Log

The Log slot is used to write a summary of an object to the logging-device defined by MkLogFileOpen and default to stderr.

The Log slot is calling the Log slot of the obj which is defined at object-setup (example: MkBufferC)

  MkTYP_R(MkBufferST).log               =  (MkLogF)            MkBufferLog_RT            ;

The log-format depending on the obeject to log. A common-prefix and a object-specific-postfix is usually available

Example: logging of a buffer object in RUBY :

require "rbmkkernel"
include MkKernel

buf = MkBufferC.CreateSTR("Hallo World")

buf.Log()

----------------------------------------------------
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }: BUFFER [0x1ccd500] { cursize=11 }                                                                    
|   |                    |          |                   | |      |         |     |                   |                                |
|   |                    |          |                   | |      |         |     |                   |                                ^ specific: START of the MkBufferC-log
|   |                    |          |                   | |      |         |     |                   ^ calling function
|   |                    |          |                   | |      |         |     ^ MqContextC: pointer
|   |                    |          |                   | |      |         ^ ref-count
|   |                    |          |                   | |      ^ MqContextC: context-id
|   |                    |          |                   | ^ debug-level
|   |                    |          |                   ^ MqContextC: S)tring, B)inary, X)none
|   |                    |          ^ thread-id
|   |                    ^ process-id
|   ^ class-name or MqContextC: object-name
^ MqContextC: S)erver, C)hild or X)none

X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:   | OBJECT [0x1ccd500] { check=Y, netHdl=0, refCnt=1, isLocal=Y, sig=59b30440, objRt=0x1cc9ef0 }
                                                                                                                                          ^ common : START of the MkObjectC-log
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:     | SELF { self=0x7fd7690d82a0, selfCreated=Y, selfRef=0 }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:     | TYPE [MkBuffer64C] { noSelf=N, delCbCnt=0, typsize=320 }
                                                                                                                                            ^ common: start of the type-log
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:       | OBJECT { type=MkTypeC, ptr=0x1ccaad0, self=(nil), refCnt=1000005, isLocal=N }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:       | obj { sig=0x59b30440, mask=0xffffffc0, size=184 }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:       | constrF=N, destrF=Y, dupF=Y, dup2F=Y, mergeF=Y, resetF=Y, logF=Y
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:       | selfCrF=Y, selfDeF=Y, selfUlF=Y, allocF=Y, freeF=Y
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:       | BASE [MkBufferC] { noSelf=N, delCbCnt=0, typsize=320 }
                                                                                                                                              ^ common: start of the base-type-log (multiple times until 'MkSuperTypeC'
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:         | OBJECT { type=MkTypeC, ptr=0x1cca990, self=(nil), refCnt=1000009, isLocal=N }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:         | obj { sig=0x59b30400, mask=0xfffffc00, size=120 }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:         | constrF=N, destrF=Y, dupF=Y, dup2F=Y, mergeF=Y, resetF=Y, logF=Y
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:         | selfCrF=Y, selfDeF=Y, selfUlF=Y, allocF=N, freeF=N
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:         | BASE [MkObjectC] { noSelf=N, delCbCnt=0, typsize=320 }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:           | OBJECT { type=MkTypeC, ptr=0x1cca850, self=(nil), refCnt=1000008, isLocal=N }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:           | obj { sig=0x59b30000, mask=0xffff0000, size=88 }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:           | constrF=N, destrF=Y, dupF=N, dup2F=Y, mergeF=N, resetF=N, logF=Y
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:           | selfCrF=Y, selfDeF=Y, selfUlF=Y, allocF=N, freeF=N
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:           | BASE [MkSuperTypeC] { check=Y, ptr=0x1ccc3d0, refCnt=1000000, self=(nil) }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:   | storage { first=0x1ccd578(ILS=Y), size=63, doFree=N }
                                                                                                                                          ^ specific : START of the MkBufferC-data-log
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:   | ils     { size=64, offset=120 }
X> {MkBuffer64C         :pid(53689):tid(0x7fd7844b4740):X:dlv(0):ctxId( 0):rc(1):ctx(0x1ccd500     ):<main>                        }:   | STRT :      11 : Hallo World
----------------------------------------------------

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

See also

MkBufferLog, MkBufferListLog, MkBufferStreamLog, ?MkLogFileLog, MkErrorLog, MkRuntimeLog, MkObjectLog

obj.LogDetail(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top log the MkObjectS verbose into the MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::LogDetail

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

See also

MkObjectC obj.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

obj.LogSimple(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top log the MkObjectS into the MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::LogSimple

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

See also

MkObjectC

MkObjectC MISC

C-API: MkObjectC_Misc_C_API - MkObjectC - various functions related to the MkObjectS …

MkErrorC* obj.ErrorCatch(std::exception* exception = NULL, MK_STRN callfunc = __builtin_FUNCTION())

top convert a programming-language-error into an ccmkkernel error … → API: ccmkkernel::MkObjectC::ErrorCatch

This function is a placeholder and have to be overloaded by the Target-Programming-Language (TPL). The goal is to handel an error-catch condition and convert an programming-language-error into an ccmkkernel-error.

This is the same as (example form c++):

mngx->ErrorFORMAT()->Catch(exception)

Example from server.cc → catch-send and reset an error

	    cl[id]->SendSTART();
	    try { 
	      ProxyItem(cl[id]);
	      cl[id]->SendEND_AND_WAIT("ECOI", 5);
	    } catch (const std::exception& e) {
	      auto err = ErrorCatch (e);
	      SendI32 (err->GetNum());
	      SendSTR (err->GetText());
	      err->Reset();
	    }

Note

The C language does not support the MkErrorCatch because there is no native error object.

If there is no error at all the MkErrorCatch does nothing and just return the MkErrorDEFAULT.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
[in]	exception	the exception object from C++, if MK_NULL the global exception object is used
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)

Returns

the ErrorDEFAULT initialized with exception value

See also

err.Raise() err.Reset(MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 callline = __builtin_LINE(), MK_BOOL force = false)

MK_BOOL obj.IsNull()

top ckeck if the object is MK_NULL → API: ccmkkernel::MkObjectC::IsNull

MkErrorC* obj.ToError()

top Error-Slot - return an error-object pre initialized with obj data. → API: ccmkkernel::MkObjectC::ToError

This slot is the same as ErrorDEFAULT with fmtobj set to this

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API

Returns

the error-object

Attention

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MK_STRN obj.ToName()

top Info-Slot - returns brief information about the obj as a string → API: ccmkkernel::MkObjectC::ToName

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API

Returns

the identification of the object as string

Attention

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MK_STRN obj.ToNameOfClass()

top Class-Slot - returns the C++-Class-Name of the obj as string → API: ccmkkernel::MkObjectC::ToNameOfClass

The Programming-Language-Micro-Kernel (PLMK) connect the C++ language with the ccmkkernel runtime. Every class-object in C++ has an conterpart as ccmkkernel type-object in the Programming-Language-Micro-Kernel (PLMK).

ObjectToNameOfType	returns the name of the ccmkkernel type
ObjectToNameOfClass	returns the name of the C++ class

MK_STRN obj.ToNameOfType()

top Type-Slot - returns the LibMkKernel-Type-Name of the obj as a string → API: ccmkkernel::MkObjectC::ToNameOfType

The Programming-Language-Micro-Kernel (PLMK) connect the C++ language with the ccmkkernel runtime. Every class-object in C++ has an conterpart as ccmkkernel type-object in the Programming-Language-Micro-Kernel (PLMK).

ObjectToNameOfType	returns the name of the libmsgque type
ObjectToNameOfClass	returns the name of the C++ class

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API

Returns

the name of the object-type as a string

MK_STRN inst.ToString()

top String-Slot - returns the string representation of the inst … → API: ccmkkernel::MkObjectC::ToString

The string is a human-readable form of the data stored in the object.

See also

slot: every class should provide a ToString function by default.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	inst	- the instance to work on

Returns

the requested string or "MK_NULL" on error

Note

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

---

MkBufferC

MkBufferC CLASS
		Export	MkBufferC - Export class functions …
		Introspection	MkBufferC - Introspection class functions …
		Misc	MkBufferC - Misc class functions …
MkBufferC TOR
		Create	Constructor - create a new MkBufferC with minimum size of internal storage …
		CreateTT	Constructor - create a new MkBufferC with an PRIMITIVE TYPE …
		CreateTLS	same as BufferCreate but require no cleanup
		CreateBUF	Constructor - create a new MkBufferC with an PRIMITIVE TYPE …
		Create64	call the BufferCreate with default type MkBuffer64S (64 byte) …
		Create256	call the BufferCreate with default type MkBuffer256S (256 byte) …
		Create1024	call the BufferCreate with default type MkBuffer1024S (1024 byte) …
		Delete	Destructor - delete a MkBufferC instance …
		Dup	Dup-Constructor - create a new MkBufferC instance as copy from an existing MkBufferC instance
		Merge	Merge-Constructor - create a new MkBufferC as a merge from an existing object …
MkBufferC SET
		SetTT	Set the MkBufferC to the val …
		SetBinaryR	Set the MkBufferC to the val …
		SetBUF	Set the MkBufferC to the val …
		SetStringR	Set the MkBufferC to the val …
		SetV	set the MkBufferC using a ... value …
		SetVL	set the MkBufferC using a va_list value …
MkBufferC GET
		GetTT	get a val_out from a MkBufferC …
		GetBFL	function to read an MkBufferListC from an MkBufferC object …
		GetBUF	get a val_out from a MkBufferC …
		GetStringR	get a val_out from a MkBufferC …
MkBufferC ACCESS
		AppendSTR	append a single string to a MkBufferC object …
		AppendStringR	append a single string to a MkBufferC object …
		AppendV	append a single string with format and ... arguments to a MkBuffer64S …
		AppendVL	append a single string with format and var_list arguments to a MkBuffer64S …
		Pop	delete str from the MkBufferC …
		Push	add str to the MkBufferC …
		ToObject	return the native language object from a MkBufferC …
MkBufferC INFO
		GetType1	return the type from a MkBufferC as single character value …
		GetType2	return the MkTypeE from a MkBufferC …
		GetType3	return the type from a MkBufferC as single character string …
		IsLocal	Check if the MkBufferC is local (temporary), not local mean global …
		Log	log the MkBufferC …
		LogS	log the short MkBufferC object data to the MkLogFileC (default: stderr) …
MkBufferC MISC
		CastTo	change the type of an MkBufferC to type …
		Cmp	compare TWO MkBufferC objects like strcmp do it for strings …
		Copy	copy the MkBufferC from srce to dest …
		Reset	reset a MkBufferC to the length zero …
		ResetFull	reset a MkBufferC to the length zero and free allocated storage…
		SizeAdd	add size storage to the buf …
		SizeNew	alloc min size storage to the buf …
		Temp	create a temporary copy of the MkBufferC buf …
		ToString	String-Slot - returns the string representation of the inst …

MkBufferC DETAIL

C-API: MkBufferC_C_API - MkBufferC - the abstract class known as buf or buffer is used to create and manage dynamic, generic, mixed typed data. …

The MkBufferC is used to store PRIMITIVE TYPE data. If ccmkkernel is working on data… ccmkkernel is working on an MkBufferC object or on a list of MkBufferC objects called MkBufferListC.

MkBufferC* CLASS

The ABSTRACT-CLASS used to store a native-type-data-item defined by PRIMITIVE TYPE …

C-Kernel-Details

The ABSTRACT-CLASS MkBufferS is used to store MkTypeE data in an MkBufferS::storage …

A new MkBufferS is always preallocated with the predefined ILS-storage (MkBufferS::ils_data), but can switch to a MALLOC-storage if the storage requirements of the user exceed the predefined MkBufferS::ilsS::size.

‍A MkBufferS never run out of storage.

The basic goal of the ILS-storage technology is to minimize the usage of MALLOC, this mean that the MkBufferS::ilsS::size should be large enought to be sufficient for the user needs.

The following conditions must always be met for the ILS memory:

• The MkBufferS::ils_data have to be always the last item in the last subclass of MkBufferS
• The MkBufferS::ilsS::offset is calculated as: MkBufferSPtr->ils_data - MkBufferSPtr.

The ABSTRACT-CLASS MkBufferS is missing the ILS-storage, the FINAL-CLASSES are:

‍MkBuffer64C, MkBuffer256C and MkBuffer1024C

See also

MkBufferListC, MkBufferStreamC

MkBufferC* CTOR / DTOR

command	synonmym
[constructor,static] MkBufferC* MkBufferC::Create(MK_NUM size = 0)	ccmkkernel::MkBufferC(MK_SIZE size = 0)
[destructor] buf.Delete()	delete buf

Example from server.cc → read a buffer-object and convert single-char-type-identifer to string.

      void BUF2 () {
	SendSTART();
	for (int i=0; i<3; i++) {
          // using a reference or a pointer to avoid a "copy", ReadBUF never return NULL
	  const MkBufferC& buf = *ReadBUF();
          // GetType3 is "const", return the type as "string"
	  SendSTR(buf.GetType3());
	  SendBUF(buf);
	}
	SendRETURN();
      }

See also

BufferGetType1 BufferGetType2 BufferGetType3

MkBufferC CLASS

NAVI: top, up

MkBufferC CLASS EXPORT

		HandleResolve	Handle-Resolve-Slot - return a MkBufferC from netHdl or MK_NULL if invalid…
		HandleGet	Handle-Get-Slot - returns a export-hdl to the MkBufferC useable for external storage

MkBufferC CLASS INTROSPECTION

		Instances	get head-instance from linked-list of MkBufferS type …
		Next	get next instance from linked-list of MkBufferS type
		Prev	get previous instance from linked-list of MkBufferS type

MkBufferC CLASS MISC

GetNull

Null-Slot - return a MkBufferC typed NULL instance …

MkBufferC CLASS DETAILS

C-API: MkBufferC_Class_C_API - MkBufferC - define the class …

MkBufferC CLASS EXPORT

MkBufferC - Export class functions …

[static] MkBufferC* MkBufferC::HandleResolve(MK_HDL netHdl)

top Handle-Resolve-Slot - return a MkBufferC from netHdl or MK_NULL if invalid… → API: ccmkkernel::MkBufferC::HandleResolve

The MkBufferHandleResolve undo the MkBufferHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	netHdl	handle former exported with MkBufferHandleGet

Returns

the required handle or MK_NULL if netHdl is invalid

MK_HDL buf.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkBufferC useable for external storage → API: ccmkkernel::MkObjectC::HandleGet

The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MkBufferHandleResolve.

By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.

The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.

example: The export-hdl is used in rpc to identify an object across the network.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on

Returns

the required export-hdl

MkBufferC CLASS INTROSPECTION

MkBufferC - Introspection class functions …

[static] MkBufferC* MkBufferC::Instances()

top get head-instance from linked-list of MkBufferS type … → API: ccmkkernel::MkBufferC::Instances

The head-instance is the last instance created.

MkBufferC* buf.Next()

top get next instance from linked-list of MkBufferS type → API: ccmkkernel::MkBufferC::Next

MkBufferC* buf.Prev()

top get previous instance from linked-list of MkBufferS type → API: ccmkkernel::MkBufferC::Prev

MkBufferC CLASS MISC

MkBufferC - Misc class functions …

[static] MkBufferC* MkBufferC::GetNull()

top Null-Slot - return a MkBufferC typed NULL instance … → API: ccmkkernel::MkBufferC::GetNull

MkBufferC TOR

C-API: MkBufferC_TOR_C_API - MkBufferC - various functions to create, initialize and destroy a MkBufferC …

[constructor,static] MkBufferC* MkBufferC::Create(MK_NUM size = 0)

top Constructor - create a new MkBufferC with minimum size of internal storage … → API: ccmkkernel::MkBufferC::Create

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferDelete is always possible, but the instance can no longer be used afterwards.

There is a libmkkernel::MkBufferCreateTT function for every PRIMITIVE TYPE.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	type	A type defined as MkTypeS with a TT postfix (default: MkBuffer64S, possible: MkBuffer64S, MkBuffer256S and MkBuffer1024S)
[in]	size	The initial size of the instance-local-storage. The MkBufferC has dynamic-memory-management, the size value is just a hint to provide enought memory for future tasks. The real size created is the maximum of type-ILS-size and size . (default: 0 = use the type-ILS-size)

Returns

The newly created MkBufferC instance, the instance is owned by the caller

See also

BufferDelete BufferDup MqReadBUF

[static] MkBufferC* MkBufferC::CreateTLS(MK_STRN tlsName, MK_BOOL resetB = true)

top same as BufferCreate but require no cleanup → API: ccmkkernel::MkBufferC::CreateTLS

• A TLS-instance only exists ONCE per thread and ONCE per tlsName in memory.
• The memory will be reused and must not be freed.
• If resetB is false (default) than no reset is done

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	tlsName	An per-thread unique name (string) to identify the reuse-able instance-storage. if tlsName is MK_NULL or "" than a MK_NULL is returned
[in]	resetB	should the new object be reset?

Returns

the new MkBufferC instance, the instance belongs to the TLS-function and does not need to be deleted.

Note

This function is intended as a replacement for MkBufferCreateTLS_T for non-C programming languages.

Attention

for usage of the TLS-storage read more at StorageCreateTLS

[constructor,static] MkBufferC* MkBufferC::CreateBUF(const MkBufferC* val)

top Constructor - create a new MkBufferC with an PRIMITIVE TYPE … → API: ccmkkernel::MkBufferC::CreateBUF

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkBufferC instance, the instance is owned by the caller

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	val	the PRIMITIVE TYPE object as data-source

[constructor,static] MkBufferC* MkBufferC::Create64(MK_NUM size = 0)

top call the BufferCreate with default type MkBuffer64S (64 byte) … → API: ccmkkernel::MkBufferC::Create64

[constructor,static] MkBufferC* MkBufferC::Create256(MK_NUM size = 0)

top call the BufferCreate with default type MkBuffer256S (256 byte) … → API: ccmkkernel::MkBufferC::Create256

[constructor,static] MkBufferC* MkBufferC::Create1024(MK_NUM size = 0)

top call the BufferCreate with default type MkBuffer1024S (1024 byte) … → API: ccmkkernel::MkBufferC::Create1024

[destructor] buf.Delete()

top Destructor - delete a MkBufferC instance … → API: libmkkernel::MkBufferDelete_RT

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. The internal memory will be freed and the object-pointer will be set to NULL. If the object-pointer is already NULL nothing will be done.
2. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
3. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
4. After a SOFT-delete, the outher shell is still alive, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.
5. On HARD-delete read more at MkSelfDeleteForce

See also

BufferCreate BufferDup MqReadBUF

[constructor] MkBufferC* buf.Dup()

top Dup-Constructor - create a new MkBufferC instance as copy from an existing MkBufferC instance → API: ccmkkernel::MkBufferC::Dup

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferDelete is always possible, but the instance can no longer be used afterwards.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on

Returns

The newly created MkBufferC instance, the instance is owned by the caller

See also

MkObjDup MkBufferDelete

[constructor] MkBufferC* buf.Merge()

top Merge-Constructor - create a new MkBufferC as a merge from an existing object … → API: ccmkkernel::MkBufferC::Merge

The Merge-Constructor create a new instance and merge all internal data from the src into the new instance. After the Merge-Constructor the BufferResetFull is called for the merge-source bus.

One usage of the Merge-Constructor is to get a lightweight-copy of a Thread-Local-Storage object for external usage.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on

Returns

The new instance or MK_NULL on error or if no Merge-Constructor is available

Attention

The new instance have to be deleted with BufferDelete

See also

BufferDup BufferResetFull BufferDelete

[constructor,static] MkBufferC::CreateTT(MK_TT val)

top

The BufferCreateTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
[constructor,static]	MkBufferC*	MkBufferC::CreateI8(MK_I8 val)	libmkkernel::MkBufferCreateI8_RT
[constructor,static]	MkBufferC*	MkBufferC::CreateI16(MK_I16 val)	libmkkernel::MkBufferCreateI16_RT
[constructor,static]	MkBufferC*	MkBufferC::CreateI32(MK_I32 val)	libmkkernel::MkBufferCreateI32_RT
[constructor,static]	MkBufferC*	MkBufferC::CreateI64(MK_I64 val)	libmkkernel::MkBufferCreateI64_RT
[constructor,static]	MkBufferC*	MkBufferC::CreateSTR(MK_STRN val)	libmkkernel::MkBufferCreateSTR_RT
[constructor,static]	MkBufferC*	MkBufferC::CreateBIN(MK_BNP val)	libmkkernel::MkBufferCreateBIN_RT
[constructor,static]	MkBufferC*	MkBufferC::CreateBOL(MK_BOL val)	libmkkernel::MkBufferCreateBOL_RT
[constructor,static]	MkBufferC*	MkBufferC::CreateFLT(MK_FLT val)	libmkkernel::MkBufferCreateFLT_RT
[constructor,static]	MkBufferC*	MkBufferC::CreateDBL(MK_DBL val)	libmkkernel::MkBufferCreateDBL_RT

Constructor - create a new MkBufferC with an PRIMITIVE TYPE …

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkBufferC instance, the instance is owned by the caller

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	val	the PRIMITIVE TYPE object as data-source

MkBufferC SET

C-API: MkBufferC_Set_C_API - MkBufferC - various functions to set buffer-data …

MkBufferC* buf.SetBinaryR(MK_BNP val)

top Set the MkBufferC to the val … → API: ccmkkernel::MkBufferC::SetBinaryR

The old value will be removed and the memory will be reset.

Returns

the MkBufferS object

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	val	the value to set the buf to

MkBufferC* buf.SetBUF(const MkBufferC* val)

top Set the MkBufferC to the val … → API: ccmkkernel::MkBufferC::SetBUF

The old value will be removed and the memory will be reset.

Returns

the MkBufferS object

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	val	the value to set the buf to

MkBufferC* buf.SetStringR(const std::string& val)

top Set the MkBufferC to the val … → API: ccmkkernel::MkBufferC::SetStringR

The old value will be removed and the memory will be reset.

Returns

the MkBufferS object

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	val	the value to set the buf to

MkBufferC* buf.SetV(MK_FST val, ... )

top set the MkBufferC using a ... value … → API: ccmkkernel::MkBufferC::SetV

The old value will be removed and the memory will be reset.

Returns

the MkBufferS object

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	val	the value to set the buf to

Precondition

val is from type c-string used as printf like format string

MkBufferC* buf.SetVL(MK_FST val, va_list var_list)

top set the MkBufferC using a va_list value … → API: ccmkkernel::MkBufferC::SetVL

The old value will be removed and the memory will be reset.

Returns

the MkBufferS object

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	val	the value to set the buf to
[in]	var_list	a variable argument list object

Precondition

val is a c-string used as printf like format string

buf.SetTT(MK_TT val)

top

The BufferSetTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	MkBufferC*	buf.SetI8(MK_I8 val)	libmkkernel::MkBufferSetI8_RT
	MkBufferC*	buf.SetI16(MK_I16 val)	libmkkernel::MkBufferSetI16_RT
	MkBufferC*	buf.SetI32(MK_I32 val)	libmkkernel::MkBufferSetI32_RT
	MkBufferC*	buf.SetI64(MK_I64 val)	libmkkernel::MkBufferSetI64_RT
	MkBufferC*	buf.SetSTR(MK_STRN val)	libmkkernel::MkBufferSetSTR_RT
	MkBufferC*	buf.SetBIN(MK_BNP val)	libmkkernel::MkBufferSetBIN_RT
	MkBufferC*	buf.SetBOL(MK_BOL val)	libmkkernel::MkBufferSetBOL_RT
	MkBufferC*	buf.SetFLT(MK_FLT val)	libmkkernel::MkBufferSetFLT_RT
	MkBufferC*	buf.SetDBL(MK_DBL val)	libmkkernel::MkBufferSetDBL_RT

Set the MkBufferC to the val …

The old value will be removed and the memory will be reset.

Returns

the MkBufferS object

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	val	the value to set the buf to

MkBufferC GET

C-API: MkBufferC_Get_C_API - MkBufferC - various functions to get buffer-data …

MkBufferListC* buf.GetBFL(MkBufferListC* val_inout = NULL)

top function to read an MkBufferListC from an MkBufferC object … → API: ccmkkernel::MkBufferC::GetBFL

This function read a buffer-item created with MqSendL_START and MqSendL_END into a temporary MkBufferListC.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in,out]	val_inout	the reference object or MK_NULL at error

• The reference object have to be non MK_NULL.
• If reference object is a refrence to a non MK_NULL object than the reference object is populated with the result.
• If reference object is a refrence to a MK_NULL object than :
  • The reference object is set to the TLS alocated object owned by the Programming-Language-Micro-Kernel (PLMK).
  • (do not free) The memory of the reference object value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
    For details on the reference object value, see: MkKernel_Storage_C_API.
• The newly created reference-object is owned by the caller.

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

MkBufferC* buf.GetBUF()

top get a val_out from a MkBufferC … → API: ccmkkernel::MkBufferC::GetBUF

The MkBufferGetTT style of functions always return a val_out or a MkErrorC.

The val_out can be a PRIMITIVE TYPE, a class-type or a pointer-type (binary, string etc).

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) - (nonnull)
[in]	buf	the MkBufferS instance to work on - (nonnull)
[out]	val_out	the value to return - (nonnull)

Attention

The return-pointer (val_out) will always be the input-pointer (buf).

std::string buf.GetStringR()

top get a val_out from a MkBufferC … → API: ccmkkernel::MkBufferC::GetStringR

The MkBufferGetTT style of functions always return a val_out or a MkErrorC.

The val_out can be a PRIMITIVE TYPE, a class-type or a pointer-type (binary, string etc).

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) - (nonnull)
[in]	buf	the MkBufferS instance to work on - (nonnull)
[out]	val_out	the value to return - (nonnull)

Attention

The return-pointer is a referenc but the embedded libmkkernel::MK_STR is owned by the MkBufferC object -> never free this pointer.

buf.GetTT()

top

The BufferGetTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	MK_I8	buf.GetI8()	libmkkernel::MkBufferGetI8_RT
	MK_I16	buf.GetI16()	libmkkernel::MkBufferGetI16_RT
	MK_I32	buf.GetI32()	libmkkernel::MkBufferGetI32_RT
	MK_I64	buf.GetI64()	libmkkernel::MkBufferGetI64_RT
	MK_STRN	buf.GetSTR()	libmkkernel::MkBufferGetSTR_RT
	MK_BNP	buf.GetBIN()	libmkkernel::MkBufferGetBIN_RT
	MK_BOL	buf.GetBOL()	libmkkernel::MkBufferGetBOL_RT
	MK_FLT	buf.GetFLT()	libmkkernel::MkBufferGetFLT_RT
	MK_DBL	buf.GetDBL()	libmkkernel::MkBufferGetDBL_RT

get a val_out from a MkBufferC …

The MkBufferGetTT style of functions always return a val_out or a MkErrorC.

The val_out can be a PRIMITIVE TYPE, a class-type or a pointer-type (binary, string etc).

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) - (nonnull)
[in]	buf	the MkBufferS instance to work on - (nonnull)
[out]	val_out	the value to return - (nonnull)

MkBufferC ACCESS

C-API: MkBufferC_Access_C_API - MkBufferC - various functions to access buffer-data …

MkBufferC* buf.AppendSTR(MK_STRN val)

top append a single string to a MkBufferC object … → API: ccmkkernel::MkBufferC::AppendSTR

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	val	the text to append to buf

Returns

the MkBufferC object with the new value

Example from server.cc → read and update a MkBufferC

	  // START - ReadBUF - Example, read a buffer-object and append a string 
	  buf = ReadBUF();
	  buf.AppendSTR("- a really log text to overwrite the already allocated space");
	  SendBUF(buf);
	  SendI32(ReadI32()+1);

MkBufferC* buf.AppendStringR(const std::string& val)

top append a single string to a MkBufferC object … → API: ccmkkernel::MkBufferC::AppendStringR

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	val	the text to append to buf

Returns

the MkBufferC object with the new value

Example from server.cc → read and update a MkBufferC

	  // START - ReadBUF - Example, read a buffer-object and append a string 
	  buf = ReadBUF();
	  buf.AppendSTR("- a really log text to overwrite the already allocated space");
	  SendBUF(buf);
	  SendI32(ReadI32()+1);

MK_I32 buf.AppendV(MK_FST printfmt, ... )

top append a single string with format and ... arguments to a MkBuffer64S … → API: ccmkkernel::MkBufferC::AppendV

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	printfmt	is a c-string used as printf like format string

Returns

the size of the string appended to the MkBuffer64S object

MK_I32 buf.AppendVL(MK_FST printfmt, va_list var_list)

top append a single string with format and var_list arguments to a MkBuffer64S … → API: ccmkkernel::MkBufferC::AppendVL

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	printfmt	is a c-string used as printf like format string
[in]	var_list	a variable argument list object

Returns

the size of the string appended to the MkBuffer64S object

MK_NUM buf.Pop(MK_STRN val)

top delete str from the MkBufferC … → API: ccmkkernel::MkBufferC::Pop

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
	val	the text (string) to remove from buf

Returns

the size of the string removed from the MkBuffer64S object

Attention

MkBufferC have to be of type libmkkernel::MK_STRT

MK_NUM buf.Push(MK_STRN val)

top add str to the MkBufferC … → API: ccmkkernel::MkBufferC::Push

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
	val	the text (string) to append to buf

Returns

the size of the string appended to the MkBuffer64S object

Attention

MkBufferC have to be of type libmkkernel::MK_STRT

MkBufferC* buf.ToObject()

top return the native language object from a MkBufferC … → API: ccmkkernel::MkBufferC::ToObject

MkBufferC INFO

C-API: MkBufferC_Info_C_API - MkBufferC - various functions to get information out of buffer-data …

MK_STRB buf.GetType1()

top return the type from a MkBufferC as single character value … → API: ccmkkernel::MkBufferC::GetType1

MK_STRB
MkBufferGetType1_RT (
  MK_RT_ARGS
  MK_BUFN const buf
)
{
  MK_INSTANCE_RT_X(buf);
  switch (buf->var.type) {
    case MK_STRT: return 'C';
    case MK_I32T: return 'I';
    case MK_DBLT: return 'D';
    case MK_I64T: return 'W';
    case MK_BINT: return 'B';
    case MK_I8T: return 'Y';
    case MK_BOLT: return 'O';
    case MK_I16T: return 'S';
    case MK_FLTT: return 'F';
    case MK_LSTT: return 'L';
  }
  return '*';
}

MkTypeE buf.GetType2()

top return the MkTypeE from a MkBufferC … → API: ccmkkernel::MkBufferC::GetType2

enum MkTypeE
MkBufferGetType2_RT (
  MK_RT_ARGS
  MK_BUFN const buf
) {
  MK_INSTANCE_RT_X(buf);
  return buf->var.type;
}

MK_STRN buf.GetType3()

top return the type from a MkBufferC as single character string … → API: ccmkkernel::MkBufferC::GetType3

MK_STRN
MkBufferGetType3_RT (
  MK_RT_ARGS
  MK_BUFN const buf
) {
  MK_INSTANCE_RT_X(buf);
  switch (buf->var.type) {
    case MK_STRT: return "C";
    case MK_I32T: return "I";
    case MK_DBLT: return "D";
    case MK_I64T: return "W";
    case MK_BINT: return "B";
    case MK_I8T:  return "Y";
    case MK_BOLT: return "O";
    case MK_I16T: return "S";
    case MK_FLTT: return "F";
    case MK_LSTT: return "L";
  }
  return "*";
}

MK_BOOL buf.IsLocal()

top Check if the MkBufferC is local (temporary), not local mean global … → API: ccmkkernel::MkBufferC::IsLocal

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on

Returns

a boolean value… yes or no

buf.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top log the MkBufferC … → API: ccmkkernel::MkObjectC::Log

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

See also

MkBufferC

buf.LogS(MK_STRN varname = "buf", const MkObjectC* fmtobj = NULL, MK_STRN callfunc = __builtin_FUNCTION())

top log the short MkBufferC object data to the MkLogFileC (default: stderr) … → API: ccmkkernel::MkBufferC::LogS

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	varname	The name of the argument to report
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)

MkBufferC MISC

C-API: MkBufferC_Misc_C_API - MkBufferC - various functions to work on buffer-data …

buf.CastTo(MkTypeE typ)

top change the type of an MkBufferC to type … → API: ccmkkernel::MkBufferC::CastTo

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	typ	cast buf to typ

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

MK_I32 buf1.Cmp(const MkBufferC* buf2)

top compare TWO MkBufferC objects like strcmp do it for strings … → API: ccmkkernel::MkBufferC::Cmp

1. if both types are equal than the native types are compared
2. if both types are non-equal than the string representation of the types are compared

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf1	the FIRST MkBufferC object to compare
[in]	buf2	the SECOND MkBufferC object to compare

Returns

Returns < 0 if buf1 is less than buf2; > 0 if buf1 is greater than buf2, and 0 if they are equal.

MkBufferC* buf.Copy(const MkBufferC* srce)

top copy the MkBufferC from srce to dest … → API: ccmkkernel::MkBufferC::Copy

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
	srce	source of the copy

Returns

the dest object

MkBufferC* buf.Reset()

top reset a MkBufferC to the length zero … → API: ccmkkernel::MkBufferC::Reset

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on

See also

buf.ResetFull()

buf.ResetFull()

top reset a MkBufferC to the length zero and free allocated storage… → API: ccmkkernel::MkBufferC::ResetFull

In addition to MkBufferC* buf.Reset() the allocated storage is freed and reset to ILS

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on

See also

MkBufferC* buf.Reset()

MkBufferC* buf.SizeAdd(MK_NUM size)

top add size storage to the buf … → API: ccmkkernel::MkBufferC::SizeAdd

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	size	The initial size of the instance-local-storage. The MkBufferC has dynamic-memory-management, the size value is just a hint to provide enought memory for future tasks. The real size created is the maximum of type-ILS-size and size . (default: 0 = use the type-ILS-size)

Returns

the input buf

MkBufferC* buf.SizeNew(MK_NUM size)

top alloc min size storage to the buf … → API: ccmkkernel::MkBufferC::SizeNew

Returns

the input buf

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	buf	the MkBufferS instance to work on
[in]	size	The initial size of the instance-local-storage. The MkBufferC has dynamic-memory-management, the size value is just a hint to provide enought memory for future tasks. The real size created is the maximum of type-ILS-size and size . (default: 0 = use the type-ILS-size)

MkBufferC* buf.Temp()

top create a temporary copy of the MkBufferC buf … → API: ccmkkernel::MkBufferC::Temp

This function always return the same global memory from the per-thread-runtime-storage initialized with buf. This storage must not be freed and should only be used for temporary-short-time usage. In theory every function-call in the same thread could overwrite this memory.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
	buf	- the source of the copy

Returns

the temporary buffer-object

Attention

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MK_STRN inst.ToString()

top String-Slot - returns the string representation of the inst … → API: ccmkkernel::MkObjectC::ToString

The string is a human-readable form of the data stored in the object.

See also

slot: every class should provide a ToString function by default.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	inst	- the instance to work on

Returns

the requested string or "MK_NULL" on error

Note

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

---

MkBufferStreamC

MkBufferStreamC CLASS
		Export	MkBufferStreamC - Export class functions …
		Introspection	MkBufferStreamC - Introspection class functions …
		Misc	MkBufferStreamC - Misc class functions …
MkBufferStreamC TOR
		Create	create and initialize an MkBufferStreamC instance …
		Create64	call the BufferStreamCreate with default type MkBufferStream64S (64 byte) …
		Create256	call the BufferStreamCreate with default type MkBufferStream256S (256 byte) …
		Create1024	call the BufferStreamCreate with default type MkBufferStream1024S (1024 byte) …
		Create16384	call the BufferStreamCreate with default type MkBufferStream16384S (16384 byte) …
		CreateTLS	same as BufferStreamCreate but require no cleanup …
		Delete	Destructor - delete a MkBufferStreamC instance …
		Dup	Dup-Constructor - create a new MkBufferStreamC instance as copy from an existing MkBufferStreamC instance …
		Merge	Merge-Constructor - create a new MkBufferStreamC as a merge from an existing object …
MkBufferStreamC READ
		ReadTT	read a val_out from the MkBufferStreamC …
		ReadALL	get a temporary MkBufferListC from all data in the MkBufferStreamC …
		ReadBFL	read a MkBufferListC from the MkBufferStreamC …
		ReadBUF	read a val_out from the MkBufferStreamC …
		ReadGetNextType	get the type (MkTypeE) of the next Item in the MkBufferStreamC or "0" if not available
		ReadGetNumItems	get the number of items left in the MkBufferStreamC …
		ReadItemExists	check if an item exists in the read-data-package …
		ReadL_END	END read a list-item-type from the MkBufferStreamC …
		ReadL_START	START read a list-item-type from the MkBufferStreamC …
		ReadLONG	read the long native object from the MkBufferStreamC …
		ReadUndo	undo the last MkBufferStreamC READ function call …
MkBufferStreamC WRITE
		WriteTT	write a PRIMITIVE TYPE into the MkBufferStreamC …
		WriteBFL	write a MkBufferListC into the MkBufferStreamC …
		WriteBUF	write a PRIMITIVE TYPE into the MkBufferStreamC …
		WriteBUS_FLAT	write a MkBufferStreamC into the MkBufferStreamC …
		WriteHDL	write the handle into the MkBufferStreamC …
		WriteL_END	END write a list-item-type into the MkBufferStreamC …
		WriteL_FLAT	write a MkBufferListC FLAT into the MkBufferStreamC …
		WriteL_START	START write a list-item-type into the MkBufferStreamC …
		WriteLONG	write the long native object into the MkBufferStreamC …
		WriteV	write format-string into the MkBufferStreamC …
		WriteVL	write format-string into the MkBufferStreamC …
MkBufferStreamC MISC
		Copy	copy the MkBufferStreamC from src to bus …
		Log	log the MkBufferStreamC …
		PosToStart	set the current-access-position to the start of MkBufferStreamC …
		Reset	reset a MkBufferStreamC to the length zero …
		ResetFull	reset a MkBufferStreamC to the length zero and free allocated storage…
		ToBFL	convert the bus into a MkBufferListC …
		ToString	String-Slot - returns the string representation of the inst …

MkBufferStreamC DETAIL

C-API: MkBufferStreamC_C_API - MkBufferStreamC - the abstract class known as bus or stream is a subclass of MkBufferC and is used for package-based-io …

The MkBufferStreamC is required to send data via a socket (pipe,tcp,uds,...). The data is organized as a continuous binary-array. Each item is preceded by type and, if applicable, size information.

‍See also: MkBufferC, MkBufferListC

C-Kernel-Details

The ABSTRACT-CLASS MkBufferStreamS has the private-parent-class MkBufferS and is used to store typed-data in a continuous binary-array at MkBufferS::storage.

private-parent-class mean:

MkBufferStreamS use the features of MkBufferS but does not expose the API

In addition to the binary-array the MkBufferStreamS also include features like:

1. the encoding: MkBufferStreamS::endian_is_wrong
2. the total number of items: MkBufferStreamS::numItems
3. current position pointer: MkBufferStreamS::cur
4. support for recursion: embedding a MkBufferStreamS into a libmkkernel::MkBufferStreamS

The MkBufferStreamS inherits the following features from MkBufferS:

1. the storage: MkBufferS::storage
2. the type: MkBufferS::type
3. the ILS: MkBufferS::ils

The ABSTRACT-CLASS MkBufferStreamS is missing the ILS-storage, the FINAL-CLASSES are:

‍MkBufferStream16384S, MkBufferStream256S, MkBufferStream64S and MkBufferStream1024S

See also

MkBufferC, MkBufferListC

MkBufferStreamC CLASS

NAVI: top, up

MkBufferStreamC CLASS EXPORT

		HandleResolve	Handle-Resolve-Slot - return a MkBufferStreamC from netHdl or MK_NULL if invalid…
		HandleGet	Handle-Get-Slot - returns a export-hdl to the MkBufferStreamC useable for external storage

MkBufferStreamC CLASS INTROSPECTION

		Instances	get head-instance from linked-list of MkBufferStreamS type …
		Next	get next instance from linked-list of MkBufferStreamS type
		Prev	get previous instance from linked-list of MkBufferStreamS type

MkBufferStreamC CLASS MISC

GetNull

Null-Slot - return a MkBufferStreamC typed NULL instance …

MkBufferStreamC CLASS DETAILS

C-API: MkBufferStreamC_Class_C_API - MkBufferStreamC - define the class …

MkBufferStreamC CLASS EXPORT

MkBufferStreamC - Export class functions …

[static] MkBufferStreamC* MkBufferStreamC::HandleResolve(MK_HDL netHdl)

top Handle-Resolve-Slot - return a MkBufferStreamC from netHdl or MK_NULL if invalid… → API: ccmkkernel::MkBufferStreamC::HandleResolve

The MkBufferStreamHandleResolve undo the MkBufferStreamHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	netHdl	handle former exported with MkBufferStreamHandleGet

Returns

the required handle or MK_NULL if netHdl is invalid

MK_HDL bus.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkBufferStreamC useable for external storage → API: ccmkkernel::MkObjectC::HandleGet

The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MkBufferStreamHandleResolve.

By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.

The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.

example: The export-hdl is used in rpc to identify an object across the network.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on

Returns

the required export-hdl

MkBufferStreamC CLASS INTROSPECTION

MkBufferStreamC - Introspection class functions …

[static] MkBufferStreamC* MkBufferStreamC::Instances()

top get head-instance from linked-list of MkBufferStreamS type … → API: ccmkkernel::MkBufferStreamC::Instances

The head-instance is the last instance created.

MkBufferStreamC* bus.Next()

top get next instance from linked-list of MkBufferStreamS type → API: ccmkkernel::MkBufferStreamC::Next

MkBufferStreamC* bus.Prev()

top get previous instance from linked-list of MkBufferStreamS type → API: ccmkkernel::MkBufferStreamC::Prev

MkBufferStreamC CLASS MISC

MkBufferStreamC - Misc class functions …

[static] MkBufferStreamC* MkBufferStreamC::GetNull()

top Null-Slot - return a MkBufferStreamC typed NULL instance … → API: ccmkkernel::MkBufferStreamC::GetNull

MkBufferStreamC TOR

C-API: MkBufferStreamC_TOR_C_API - MkBufferStreamC - various functions to create and destroy a MkBufferStreamC …

[constructor,static] MkBufferStreamC* MkBufferStreamC::Create(MK_NUM size = 0)

top create and initialize an MkBufferStreamC instance … → API: ccmkkernel::MkBufferStreamC::Create

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferStreamDelete is always possible, but the instance can no longer be used afterwards.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	type	A type defined as MkTypeS with a TT postfix (default: MkBufferStream1024S, possible: MkBufferStream16384S, MkBufferStream256S, MkBufferStream64S and MkBufferStream1024S)
[in]	size	The initial size of the instance-local-storage. The MkBufferStreamC has dynamic-memory-management, the size value is just a hint to provide enought memory for future tasks. The real size created is the maximum of type-ILS-size and size . (default: 0 = use the type-ILS-size)

Returns

The newly created MkBufferStreamC instance, the instance is owned by the caller

[constructor,static] MkBufferStreamC* MkBufferStreamC::Create64(MK_NUM size = 0)

top call the BufferStreamCreate with default type MkBufferStream64S (64 byte) … → API: ccmkkernel::MkBufferStreamC::Create64

[constructor,static] MkBufferStreamC* MkBufferStreamC::Create256(MK_NUM size = 0)

top call the BufferStreamCreate with default type MkBufferStream256S (256 byte) … → API: ccmkkernel::MkBufferStreamC::Create256

[constructor,static] MkBufferStreamC* MkBufferStreamC::Create1024(MK_NUM size = 0)

top call the BufferStreamCreate with default type MkBufferStream1024S (1024 byte) … → API: ccmkkernel::MkBufferStreamC::Create1024

[constructor,static] MkBufferStreamC* MkBufferStreamC::Create16384(MK_NUM size = 0)

top call the BufferStreamCreate with default type MkBufferStream16384S (16384 byte) … → API: ccmkkernel::MkBufferStreamC::Create16384

[static] MkBufferStreamC* MkBufferStreamC::CreateTLS(MK_STRN tlsName, MK_BOOL resetB = true)

top same as BufferStreamCreate but require no cleanup … → API: ccmkkernel::MkBufferStreamC::CreateTLS

• A TLS-instance only exists ONCE per thread and ONCE per tlsName in memory.
• The memory will be reused and must not be freed.
• If resetB is false (default) than no reset is done

Example from perfserver.cc → performance test with TLS storage

    void BUST () {
      auto bus = MkBufferStreamC::CreateTLS( "perfserver-BUST" );
      while (ReadItemExists()) {
        bus->WriteBUF(ReadBUF());
      }
      bus->PosToStart();
      SendSTART();
      while (bus->ReadItemExists()) {
        SendBUF(bus->ReadBUF());
      }
      SendRETURN();
    }

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	tlsName	An per-thread unique name (string) to identify the reuse-able instance-storage. if tlsName is MK_NULL or "" than a MK_NULL is returned
[in]	resetB	should the new object be reset?

Returns

the new MkBufferStreamC instance, the instance belongs to the TLS-function and does not need to be deleted.

Note

This function is intended as a replacement for MkBufferStreamCreateTLS_T for non-C programming languages.

Attention

for usage of the TLS-storage read more at StorageCreateTLS

[destructor] bus.Delete()

top Destructor - delete a MkBufferStreamC instance … → API: libmkkernel::MkBufferStreamDelete_RT

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. The internal memory will be freed and the object-pointer will be set to NULL. If the object-pointer is already NULL nothing will be done.
2. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
3. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
4. After a SOFT-delete, the outher shell is still alive, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.
5. On HARD-delete read more at MkSelfDeleteForce

See also

BufferStreamCreate BufferStreamDup

[constructor] MkBufferStreamC* src.Dup()

top Dup-Constructor - create a new MkBufferStreamC instance as copy from an existing MkBufferStreamC instance … → API: ccmkkernel::MkBufferStreamC::Dup

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferStreamDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkBufferStreamC instance, the instance is owned by the caller

See also

MkObjDup MkBufferStreamDelete

[constructor] MkBufferStreamC* bus.Merge()

top Merge-Constructor - create a new MkBufferStreamC as a merge from an existing object … → API: ccmkkernel::MkBufferStreamC::Merge

The Merge-Constructor create a new instance and merge all internal data from the src into the new instance. After the Merge-Constructor the BufferStreamResetFull is called for the merge-source bus.

One usage of the Merge-Constructor is to get a lightweight-copy of a Thread-Local-Storage object for external usage.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on - (nonnull)

Returns

The new instance or MK_NULL on error or if no Merge-Constructor is available

Attention

The new instance have to be deleted with BufferStreamDelete

See also

BufferStreamDup BufferStreamResetFull BufferStreamDelete

MkBufferStreamC READ

C-API: MkBufferStreamC_Read_C_API - MkBufferStreamC - various functions to 'read' data from a MkBufferStreamS …

Read is done at the position of MkBufferStreamS::storage->cur. After read the cur is incemented with read-sizeof characters.

MkBufferListC* bus.ReadALL(MkBufferListC* val_inout = NULL)

top get a temporary MkBufferListC from all data in the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::ReadALL

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in,out]	val_inout	the reference object or MK_NULL at error

• The reference object have to be non MK_NULL.
• If reference object is a refrence to a non MK_NULL object than the reference object is populated with the result.
• If reference object is a refrence to a MK_NULL object than :
  • The reference object is set to the TLS alocated object owned by the Programming-Language-Micro-Kernel (PLMK).
  • (do not free) The memory of the reference object value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
    For details on the reference object value, see: MkKernel_Storage_C_API.
• The newly created reference-object is owned by the caller.

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

See also

BufferStreamReadBFL

MkBufferListC* bus.ReadBFL()

top read a MkBufferListC from the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::ReadBFL

The MkBufferListC represent a list-item-type (libmkkernel::MK_LSTT from the MkBufferStreamC. A list-item-type is created with bus.WriteL_START() and bus.WriteL_END() and collect multiple items into one item, the list-item-type.

A list-item-type can have an other list-item-type as item, this create a tree-like structure of items.

If the next item in the read-data-package is not a list-item-type than an error is raised. To get all data in the read-data-package as one single MkBufferListC use the MqReadALL.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[out]	val_out	the MkBufferListC as return-value

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

See also

BufferStreamReadALL BufferStreamWriteBFL

Attention

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MkBufferC* bus.ReadBUF()

top read a val_out from the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::ReadBUF

The MkBufferStreamReadTT style of functions always return a val_out or a MkErrorC.

Precondition

The val_out can be a PRIMITIVE TYPE, a class-type or a pointer-type (binary, string etc).

After every read the current-access-position is incremented by one to get the next item for the next read.

To reset the current-access-position to the start use bus.PosToStart().

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[out]	val_out	the new value

MkTypeE bus.ReadGetNextType()

top get the type (MkTypeE) of the next Item in the MkBufferStreamC or "0" if not available → API: ccmkkernel::MkBufferStreamC::ReadGetNextType

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on

Returns

the type

MK_NUM bus.ReadGetNumItems()

top get the number of items left in the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::ReadGetNumItems

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on

Returns

the number of items as integer

MK_BOOL bus.ReadItemExists()

top check if an item exists in the read-data-package … → API: ccmkkernel::MkBufferStreamC::ReadItemExists

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on

Returns

boolean, true or false

bus.ReadL_END()

top END read a list-item-type from the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::ReadL_END

bus.ReadL_START(MkBufferC* buf = NULL)

top START read a list-item-type from the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::ReadL_START

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in]	buf	MK_NULL or a MkBufferC with a list-item-type or an error is raised.

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

MK_LONG bus.ReadLONG()

top read the long native object from the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::ReadLONG

on 64bit use a BufferStreamReadI32 and on 32bit use a BufferStreamReadI64

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[out]	val_out	the native long object to read

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

this api-function is NOT portable

See also

bus.WriteLONG(MK_LONG val)

bus.ReadUndo()

top undo the last MkBufferStreamC READ function call … → API: ccmkkernel::MkBufferStreamC::ReadUndo

Decrement the current-access-position by one, to the start of the last read body-item. The next read function call will extract the same item again. Only one undo level is supported.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

bus.ReadTT()

top

The BufferStreamReadTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	MK_I8	bus.ReadI8()	libmkkernel::MkBufferStreamReadI8_RT
	MK_I32	bus.ReadI32()	libmkkernel::MkBufferStreamReadI32_RT
	MK_I64	bus.ReadI64()	libmkkernel::MkBufferStreamReadI64_RT
	MK_STRN	bus.ReadSTR()	libmkkernel::MkBufferStreamReadSTR_RT
	MK_BNP	bus.ReadBIN()	libmkkernel::MkBufferStreamReadBIN_RT
	MK_BOL	bus.ReadBOL()	libmkkernel::MkBufferStreamReadBOL_RT
	MK_FLT	bus.ReadFLT()	libmkkernel::MkBufferStreamReadFLT_RT
	MK_DBL	bus.ReadDBL()	libmkkernel::MkBufferStreamReadDBL_RT

read a val_out from the MkBufferStreamC …

The MkBufferStreamReadTT style of functions always return a val_out or a MkErrorC.

Precondition

The val_out can be a PRIMITIVE TYPE, a class-type or a pointer-type (binary, string etc).

After every read the current-access-position is incremented by one to get the next item for the next read.

To reset the current-access-position to the start use bus.PosToStart().

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[out]	val_out	the new value

MkBufferStreamC WRITE

C-API: MkBufferStreamC_Write_C_API - MkBufferStreamC - various functions to write into a MkBufferStreamS …

Write is done at the position of MkBufferStreamS::storage->cur. After write the cur is incemented with write-sizeof characters.

bus.WriteBFL(const MkBufferListC* bfl)

top write a MkBufferListC into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteBFL

The MkBufferListC represent a list-item-type (libmkkernel::MK_LSTT from the MkBufferStreamC. A list-item-type is created with bus.WriteL_START() and bus.WriteL_END() and collect multiple items into one item, the list-item-type.

A list-item-type can have an other list-item-type as item, this create a tree-like structure of items.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in]	bfl	the MkBufferListC to insert

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

See also

BufferStreamWriteL_FLAT BufferStreamReadBFL

bus.WriteBUF(const MkBufferC* val)

top write a PRIMITIVE TYPE into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteBUF

After every write the current-access-position is incremented by one, use MkBufferStreamC* bus.Reset() to reset.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in]	val	the new PRIMITIVE TYPE

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

bus.WriteBUS_FLAT(const MkBufferStreamC* add)

top write a MkBufferStreamC into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteBUS_FLAT

The add is appended to bus

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in]	add	the MkBufferStreamC to append

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

bus.WriteHDL(MK_I32 val)

top write the handle into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteHDL

The handle is a special type to represent an object as numeric-type able to be stored into an external-software.

The handle support the following API:

• MkObjectHandleGet → The conversion from an instance into a handle.
• MkObjectHandleResolve → The conversion from an handle into an instance.
• MkObjectHandleDelete → The handle is deleted. Future use of the same handle will generate an error.

bus.WriteL_END()

top END write a list-item-type into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteL_END

bus.WriteL_FLAT(MkBufferListC* bfl)

top write a MkBufferListC FLAT into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteL_FLAT

A MkBufferListC can be written into a MkBufferStreamC using:

command	description	example
BufferStreamWriteBFL	one item as list-item-type	… [ itm1 itm2 itm3 itm4 ] …
BufferStreamWriteL_FLAT	a sequence of single items	… itm1 itm2 itm3 itm4 …

The second is called FLAT because the shell of the list-item-type is missing .

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in]	bfl	the MkBufferListC to insert

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

See also

MkBufferStreamReadBFL

bus.WriteL_START()

top START write a list-item-type into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteL_START

bus.WriteLONG(MK_LONG val)

top write the long native object into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteLONG

on 64bit use a MkBufferStreamWriteI64 and on 32bit use a MkBufferStreamWriteI32

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in]	val	the native long object to write

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

this api-function is NOT portable

See also

MK_LONG bus.ReadLONG()

bus.WriteV(MK_STRN fmt, ... )

top write format-string into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteV

bus.WriteVL(MK_STRN fmt, va_list ap)

top write format-string into the MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::WriteVL

bus.WriteTT(MK_TT val)

top

The BufferStreamWriteTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
		bus.WriteI8(MK_I8 val)	libmkkernel::MkBufferStreamWriteI8_RT
		bus.WriteI32(MK_I32 val)	libmkkernel::MkBufferStreamWriteI32_RT
		bus.WriteI64(MK_I64 val)	libmkkernel::MkBufferStreamWriteI64_RT
		bus.WriteSTR(MK_STRN val, MK_NUM len = -1)	libmkkernel::MkBufferStreamWriteSTR_RT
		bus.WriteBIN(MK_BNP val)	libmkkernel::MkBufferStreamWriteBIN_RT
		bus.WriteBOL(MK_BOL val)	libmkkernel::MkBufferStreamWriteBOL_RT
		bus.WriteFLT(MK_FLT val)	libmkkernel::MkBufferStreamWriteFLT_RT
		bus.WriteDBL(MK_DBL val)	libmkkernel::MkBufferStreamWriteDBL_RT

write a PRIMITIVE TYPE into the MkBufferStreamC …

After every write the current-access-position is incremented by one, use MkBufferStreamC* bus.Reset() to reset.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in]	val	the new PRIMITIVE TYPE

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

MkBufferStreamC MISC

C-API: MkBufferStreamC_Misc_C_API - MkBufferStreamC - various functions to create and destroy a MkBufferStreamS …

MkBufferStreamC* bus.Copy(const MkBufferStreamC* src)

top copy the MkBufferStreamC from src to bus … → API: ccmkkernel::MkBufferStreamC::Copy

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
	src	source of the copy

Returns

the bus instance

bus.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top log the MkBufferStreamC … → API: ccmkkernel::MkObjectC::Log

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

bus.PosToStart()

top set the current-access-position to the start of MkBufferStreamC … → API: ccmkkernel::MkBufferStreamC::PosToStart

MkBufferStreamC* bus.Reset()

top reset a MkBufferStreamC to the length zero … → API: ccmkkernel::MkBufferStreamC::Reset

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on

See also

bus.ResetFull()

bus.ResetFull()

top reset a MkBufferStreamC to the length zero and free allocated storage… → API: ccmkkernel::MkBufferStreamC::ResetFull

In addition to MkBufferStreamC* bus.Reset() the allocated storage is freed and reset to ILS. This is usefull if the internal storage was filled once with a huge amount of data.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on

See also

MkBufferStreamC* bus.Reset()

MkBufferListC* bus.ToBFL()

top convert the bus into a MkBufferListC … → API: ccmkkernel::MkBufferStreamC::ToBFL

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bus	the MkBufferStreamS instance to work on

Returns

the MkBufferListC instance requested or MkBufferListGetNull on error

Note

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MK_STRN inst.ToString()

top String-Slot - returns the string representation of the inst … → API: ccmkkernel::MkObjectC::ToString

The string is a human-readable form of the data stored in the object.

See also

slot: every class should provide a ToString function by default.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	inst	- the instance to work on

Returns

the requested string or "MK_NULL" on error

Note

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

---

MkBufferListC

MkBufferListC CLASS
		Export	MkBufferListC - Export class functions …
		Introspection	MkBufferListC - Introspection class functions …
		Misc	MkBufferListC - Misc class functions …
MkBufferListC TOR
		Create	Constructs a MkBufferC instance with size storage…
		CreateLA	Constructs a MkBufferListC instance with an other MkBufferListC OR a list of arguments (only in NON C)
		CreateTLS	same as BufferListCreate but require no cleanup …
		CreateVA	Constructs a MkBufferListC instance with a varargs argument that ends with MK_NULL …
		CreateVAL	Constructs a MkBufferListC instance with a va_list argument …
		CreateVC	Constructs a MkBufferListC instance with a argc/argv data from a list of strings …
		Delete	Destructor - delete a MkBufferListC instance …
		Dup	Dup-Constructor - create a new MkBufferListC instance as copy from an existing MkBufferListC instance …
		Merge	Merge-Constructor - constructs a MkBufferListC instance as a merge from an existing MkBufferListC instance …
MkBufferListC APPEND
		AppendTT	append a native PRIMITIVE TYPE object to a MkBufferListC …
		AppendBUF	append a native PRIMITIVE TYPE object to a MkBufferListC …
		AppendG	append a native PRIMITIVE TYPE object to a MkBufferListC …
		AppendLA	append a variable number of MkBufferC object's to an MkBufferListC object using an other MkBufferListC OR a list of arguments (only in NON C)
		AppendLP	copy a MkBufferListS list into an MkBufferListS object on position …
		AppendStringR	append a native PRIMITIVE TYPE object to a MkBufferListC …
		AppendUP	append a MkBufferC item into an MkBufferListC object on position …
		AppendV	append an printf like format object to the end of an MkBufferListS object …
		AppendVA	append a variable number of strings to an MkBufferListS object …
		AppendVAL	append a variable number of strings to an MkBufferListS object …
		AppendVC	append a argc/argv list of strings to an MkBufferListS object …
		AppendVL	append an printf like format object to the end of an MkBufferListS object …
MkBufferListC CHECK
		CheckOptionTT	search for opt in MkBufferListS list and fill var with opt_argument or the defval value …
		CheckOption	search for boolean option in MkBufferListS list and return libmkkernel::MK_BOL value …
		CheckOptionBUF	search for opt in MkBufferListS list and fill var with opt_argument or the defval value …
MkBufferListC INDEX
		IndexDelete	delete the index'th list item from the MkBufferListS object …
		IndexGet	get (read only) the index object from bfl …
		IndexGetBUF	get the index element from MkBufferListC ... if not available… create it. …
		IndexGetSTR	get the index element from MkBufferListC ... as string. …
		IndexSet	set the index object from bfl …
		IndexSetBUF	set the index element from MkBufferListC ... if not available… createspace …
		IndexSetSTR	set the index element from MkBufferListC ... to string… if not available… create space …
		IndexExtract	extract (read & delete) the index object from bfl …
MkBufferListC LOG
		Log	write the detail-summary of the MkBufferListC to MkLogFileC (default: stderr) …
		LogS	write the short-summary of the MkBufferListC to MkLogFileC (default: stderr) …
		LogSS	write the very-short-summary of the MkBufferListC to MkLogFileC (default: stderr) …
		LogSSS	write the very-very-short-summary of the MkBufferListC to MkLogFileC (default: stderr) …
MkBufferListC MISC
		FileGlob	create a new MkBufferListC using the result from a filesystem glob operation …
		Move	move all internal data from from to the end of to …
		Copy	copy all internal data from src to tgt …
		PositionMerge	merge a MkBufferListS list into an MkBufferListS object on position …
		Cmp	compare two buffer-list …
		Reserve	reserve num items in a MkBufferListC object …
		Reset	reset a MkBufferListC object …
		SearchC	search libmkkernel::MK_STR item from a MkBufferListS object starting at startindex …
		Size	get the number-of-items in the bfl …
		Sort	sort a MkBufferListC …
		ToBuffer	Export a bfl into an MkBufferC using an MkBufferStreamC …
		ToList	get a target-language list representation of the bfl …
		ToString	get a string representation of the bfl

MkBufferListC DETAIL

C-API: MkBufferListC_C_API - MkBufferListC - the class known as bfl or buffer-list is used to create and manage a list of MkBufferC …

The MkBufferListC is used to store a list of MkBufferC data into an array. In contrast to the MkBufferStreamC, each individual item can be accessed directly with the MkBufferListC.

MkBufferListC* CLASS

The CLASS used to store a list of MkBufferS items into a flat array…

C-Kernel-Details

The CLASS MkBufferListS is used to store a list of MkBufferS into an MkBufferListS::data array. To access an MkBufferS item use:

‍0 <= index < MkBufferListS::cursize

A new MkBufferListS is always preallocated with the predefined ILS-storage (MkBufferListS::bls), but can switch to a MALLOC-storage if the storage requirements of the user exceed the predefined ILS-storage-size (MkBufferListS_bls_size).

‍A MkBufferListS never run out of storage.

See also

MkBufferC, MkBufferStreamC

MkBufferListC* CTOR / DTOR

command	alias
[constructor,static] MkBufferListC* MkBufferListC::Create(MK_NUM size = 0)	ccmkkernel::MkBufferListC(MK_NUM num = 0)
[destructor] bfl.Delete()	delete bfl

MkBufferListC CLASS

NAVI: top, up

MkBufferListC CLASS EXPORT

		HandleResolve	Handle-Resolve-Slot - return a MkBufferListC from netHdl or MK_NULL if invalid…
		HandleGet	Handle-Get-Slot - returns a export-hdl to the MkBufferListC useable for external storage

MkBufferListC CLASS INTROSPECTION

		Instances	get head-instance from linked-list of MkBufferListS type …
		Next	get next instance from linked-list of MkBufferListS type
		Prev	get previous instance from linked-list of MkBufferListS type

MkBufferListC CLASS MISC

GetNull

Null-Slot - return a MkBufferListC typed NULL instance …

MkBufferListC CLASS DETAILS

C-API: MkBufferListC_Class_C_API - MkBufferListC - define the class …

MkBufferListC CLASS EXPORT

MkBufferListC - Export class functions …

[static] MkBufferListC* MkBufferListC::HandleResolve(MK_HDL netHdl)

top Handle-Resolve-Slot - return a MkBufferListC from netHdl or MK_NULL if invalid… → API: ccmkkernel::MkBufferListC::HandleResolve

The MkBufferListHandleResolve undo the MkBufferListHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	netHdl	handle former exported with MkBufferListHandleGet

Returns

the required handle or MK_NULL if netHdl is invalid

MK_HDL bfl.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkBufferListC useable for external storage → API: ccmkkernel::MkObjectC::HandleGet

The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MkBufferListHandleResolve.

By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.

The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.

example: The export-hdl is used in rpc to identify an object across the network.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on

Returns

the required export-hdl

MkBufferListC CLASS INTROSPECTION

MkBufferListC - Introspection class functions …

[static] MkBufferListC* MkBufferListC::Instances()

top get head-instance from linked-list of MkBufferListS type … → API: ccmkkernel::MkBufferListC::Instances

The head-instance is the last instance created.

MkBufferListC* bfl.Next()

top get next instance from linked-list of MkBufferListS type → API: ccmkkernel::MkBufferListC::Next

MkBufferListC* bfl.Prev()

top get previous instance from linked-list of MkBufferListS type → API: ccmkkernel::MkBufferListC::Prev

MkBufferListC CLASS MISC

MkBufferListC - Misc class functions …

[static] MkBufferListC* MkBufferListC::GetNull()

top Null-Slot - return a MkBufferListC typed NULL instance … → API: ccmkkernel::MkBufferListC::GetNull

MkBufferListC TOR

C-API: MkBufferListC_TOR_C_API - MkBufferListC - various functions to create and destroy a MkBufferListS …

[constructor,static] MkBufferListC* MkBufferListC::Create(MK_NUM size = 0)

top Constructs a MkBufferC instance with size storage… → API: ccmkkernel::MkBufferListC::Create

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferListDelete is always possible, but the instance can no longer be used afterwards.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	size	The initial size of the instance-local-storage. The MkBufferListC has dynamic-memory-management, the size value is just a hint to provide enought memory for future tasks. The real size created is the maximum of type-ILS-size and size . (default: 0 = use the type-ILS-size)

Returns

The newly created MkBufferListC instance, the instance is owned by the caller

[constructor,static] MkBufferListC* MkBufferListC::CreateLA(MkBufferListC* args)

top Constructs a MkBufferListC instance with an other MkBufferListC OR a list of arguments (only in NON C) → API: ccmkkernel::MkBufferListC::CreateLA

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferListDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkBufferListC instance, the instance is owned by the caller

See also

BufferListDup

[static] MkBufferListC* MkBufferListC::CreateTLS(MK_STRN tlsName, MK_BOOL resetB = true)

top same as BufferListCreate but require no cleanup … → API: ccmkkernel::MkBufferListC::CreateTLS

• A TLS-instance only exists ONCE per thread and ONCE per tlsName in memory.
• The memory will be reused and must not be freed.
• If resetB is false (default) than no reset is done

Example from perfserver.cc → performance test with TLS storage

    void BFLT () {
      auto bfl = MkBufferListC::CreateTLS( "perfserver-BFLT" ) ;
      while (ReadItemExists()) {
        bfl->AppendBUF(ReadBUF());
      }
      SendSTART();
      auto size = bfl->Size();
      for (MK_NUM i=0; i<size; ++i) {
        SendBUF(bfl->IndexGet(i));
      }
      SendRETURN();
    }

Example from LibSq3LiteRpcClient.tcl → callback dealing the temporary TLS data

# Intro     : Example from tcl-rpc-client of using a CreateTLS-like function (here for MkBufferListC) 
#             to improve code speed and readability.
#
# Problem   : This function is used to invoke a callback (myCb). The arguments come from the argument 
#             list args *and* from a service call (ReadBFL).
#             The problem is that ReadBFL is called *twice* and the *second* call overwrites the value 
#             of the *first* call because CreateTLS always returns *the same* MkBufferListC, just 
#             replaced with a new set of values.
#
# Solution  : The MkBufferListC instance returned by ReadBFL is copied into another MkBufferListC 
#             instance returned by CreateTLS.
#             The "CreateTLS" instance is only created *once* and reused, *but* now we can create as 
#             many MkBufferListC instances as we want, because "CreateTLS" distinguishes the returned 
#             instances by the string identifier. 
#             WITHOUT "CreateTLS" a copy would have to be created (Dup) which would then be destroyed 
#             *after* the callback is called (Delete)

proc Sq3LiteRpcClientExecV2CB {rpc myCb args} {
  set valL [MkBufferListC CreateTLS "Sq3LiteRpcClientExecV2CB→valL"]
  set colL [MkBufferListC CreateTLS "Sq3LiteRpcClientExecV2CB→colL"]

  $valL Copy [$rpc ReadBFL]
  $colL Copy [$rpc ReadBFL]

  $myCb {*}$args $valL $colL
}

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	tlsName	An per-thread unique name (string) to identify the reuse-able instance-storage. if tlsName is MK_NULL or "" than a MK_NULL is returned
[in]	resetB	should the new object be reset?

Returns

the new MkBufferListC instance, the instance belongs to the TLS-function and does not need to be deleted.

Attention

for usage of the TLS-storage read more at StorageCreateTLS

[constructor,static] MkBufferListC* MkBufferListC::CreateVA(MK_STRN arg0, ... )

top Constructs a MkBufferListC instance with a varargs argument that ends with MK_NULL … → API: ccmkkernel::MkBufferListC::CreateVA

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferListDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkBufferListC instance, the instance is owned by the caller

[constructor,static] MkBufferListC* MkBufferListC::CreateVAL(MK_STRN arg0, va_list var_list)

top Constructs a MkBufferListC instance with a va_list argument … → API: ccmkkernel::MkBufferListC::CreateVAL

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferListDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkBufferListC instance, the instance is owned by the caller

See also

va_start(3), va_arg(3), va_copy(3), and va_end(3)

[constructor,static] MkBufferListC* MkBufferListC::CreateVC(MK_NUM argc, MK_STRN argv[] )

top Constructs a MkBufferListC instance with a argc/argv data from a list of strings … → API: ccmkkernel::MkBufferListC::CreateVC

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferListDelete is always possible, but the instance can no longer be used afterwards.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
	argc	the argc from the initial main function
	argv	the arguments from the initial main function

Returns

The newly created MkBufferListC instance, the instance is owned by the caller

Attention

a MkBufferListC instance is always created… even if argc = 0

See also

MqCtxTypeS::argvFix

int main (int argc, char *argv[])
{
  MK_BFL largs = MkBufferListCreateVC(argc, argv);
....
}

[destructor] bfl.Delete()

top Destructor - delete a MkBufferListC instance … → API: libmkkernel::MkBufferListDelete_RT

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. The internal memory will be freed and the object-pointer will be set to NULL. If the object-pointer is already NULL nothing will be done.
2. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
3. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
4. After a SOFT-delete, the outher shell is still alive, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.
5. On HARD-delete read more at MkSelfDeleteForce

See also

BufferListCreate BufferListDup MqReadBFL

[constructor] MkBufferListC* bfl.Dup()

top Dup-Constructor - create a new MkBufferListC instance as copy from an existing MkBufferListC instance … → API: ccmkkernel::MkBufferListC::Dup

The new instance belongs to the caller and may have to be released if necessary. A manual release using BufferListDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkBufferListC instance, the instance is owned by the caller

See also

MkObjDup

[constructor] MkBufferListC* bfl.Merge()

top Merge-Constructor - constructs a MkBufferListC instance as a merge from an existing MkBufferListC instance … → API: ccmkkernel::MkBufferListC::Merge

The Merge-Constructor create a new object-shell, and take-over all the internal data from the source-object. After the Merge-Constructor the source-object is empty as if a BufferListReset was called.

One usage of the Merge-Constructor is to get a lightweight-copy of a Thread-Local-Storage object for external usage.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on

Returns

The new instance or MK_NULL on error or if no Merge-Constructor is available

Attention

The new instance have to be deleted with BufferListDelete

See also

BufferListDup

MkBufferListC APPEND

C-API: MkBufferListC_Append_C_API - MkBufferListC - various functions to 'append' to a MkBufferListS …

bfl.AppendBUF(MkBufferC* val)

top append a native PRIMITIVE TYPE object to a MkBufferListC … → API: ccmkkernel::MkBufferListC::AppendBUF

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	val	the PRIMITIVE TYPE object data to append

Attention

After the insert the buffer is owed by the buf object -> do not free val.

bfl.AppendG(MK_LONG val)

top append a native PRIMITIVE TYPE object to a MkBufferListC … → API: ccmkkernel::MkBufferListC::AppendG

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	val	the PRIMITIVE TYPE object data to append

MkBufferListC* bfl.AppendLA(MkBufferListC* args)

top append a variable number of MkBufferC object's to an MkBufferListC object using an other MkBufferListC OR a list of arguments (only in NON C) → API: ccmkkernel::MkBufferListC::AppendLA

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	args	the MkBufferListC object

MkBufferListC* bfl.AppendLP(MkBufferListC* addBufL, MK_NUM position = -1)

top copy a MkBufferListS list into an MkBufferListS object on position … → API: ccmkkernel::MkBufferListC::AppendLP

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	addBufL	the MkBufferListS object to append
[in]	position	insert in at position, shift all following arguments one up

Attention

Set position to 0 to append to the beginning or set position to -1 to append to the end

bfl.AppendStringR(const std::string& val)

top append a native PRIMITIVE TYPE object to a MkBufferListC … → API: ccmkkernel::MkBufferListC::AppendStringR

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	val	the PRIMITIVE TYPE object data to append

bfl.AppendUP(MkBufferC* addBuf, MK_NUM position = -1)

top append a MkBufferC item into an MkBufferListC object on position … → API: ccmkkernel::MkBufferListC::AppendUP

• set position to 0 to append to the beginning
• set position to -1 to append to the end
• after append the addBuf belongs to bfl

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	addBuf	the MkBufferC object to append
[in]	position	insert in at position, shift all following arguments one up

Attention

After append the object addBuf will be owned by bfl.

bfl.AppendV(MK_FST printfmt, ... )

top append an printf like format object to the end of an MkBufferListS object … → API: ccmkkernel::MkBufferListC::AppendV

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	printfmt	is a c-string used as printf like format string

MkBufferListC* bfl.AppendVA(MK_STRN arg0, ... )

top append a variable number of strings to an MkBufferListS object … → API: ccmkkernel::MkBufferListC::AppendVA

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	arg0	anchor element for ...

Attention

The C-Api requires a MK_NULL item on end to signal… end-of-list.

MkBufferListC* bfl.AppendVAL(MK_STRN arg0, va_list var_list)

top append a variable number of strings to an MkBufferListS object … → API: ccmkkernel::MkBufferListC::AppendVAL

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	arg0	anchor element for ...
[in]	var_list	a variable argument list object

Attention

The C-Api requires a MK_NULL item on end to signal… end-of-list.

MkBufferListC* bfl.AppendVC(MK_NUM argc, MK_STRN argv[] )

top append a argc/argv list of strings to an MkBufferListS object … → API: ccmkkernel::MkBufferListC::AppendVC

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	argc	the number of arguments in argv, if <0 than check for MK_NULL in argv
[in]	argv	the array of strings to append

bfl.AppendVL(MK_FST printfmt, va_list var_list)

top append an printf like format object to the end of an MkBufferListS object … → API: ccmkkernel::MkBufferListC::AppendVL

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	printfmt	is a c-string used as printf like format string
[in]	var_list	a variable argument list object

bfl.AppendTT(MK_TT val)

top

The BufferListAppendTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
		bfl.AppendI8(MK_I8 val)	libmkkernel::MkBufferListAppendI8_RT
		bfl.AppendI16(MK_I16 val)	libmkkernel::MkBufferListAppendI16_RT
		bfl.AppendI32(MK_I32 val)	libmkkernel::MkBufferListAppendI32_RT
		bfl.AppendI64(MK_I64 val)	libmkkernel::MkBufferListAppendI64_RT
		bfl.AppendSTR(MK_STRN val)	libmkkernel::MkBufferListAppendSTR_RT
		bfl.AppendBIN(MK_BNP val)	libmkkernel::MkBufferListAppendBIN_RT
		bfl.AppendBOL(MK_BOL val)	libmkkernel::MkBufferListAppendBOL_RT
		bfl.AppendFLT(MK_FLT val)	libmkkernel::MkBufferListAppendFLT_RT
		bfl.AppendDBL(MK_DBL val)	libmkkernel::MkBufferListAppendDBL_RT

append a native PRIMITIVE TYPE object to a MkBufferListC …

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	val	the PRIMITIVE TYPE object data to append

MkBufferListC CHECK

C-API: MkBufferListC_Check_C_API - MkBufferListC - various functions to 'check' a MkBufferListS …

This functions are used for parsing command-line-arguments.

MK_BOOL bfl.CheckOption(MK_STRN opt, MK_BOOL onlyFirst = false)

top search for boolean option in MkBufferListS list and return libmkkernel::MK_BOL value … → API: ccmkkernel::MkBufferListC::CheckOption

1. If opt is found, the opt is deleted from the MkBufferListC.
2. If opt starting with a - or a -- the opt is treated as true
3. If opt starting with a + or a ++ the opt is treated as false
4. If opt does not start with a - or a + than the opt is treated as true
5. It multiple opt are available all opt are checked and deleted.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on or MK_NULL
[in]	opt	Find opt string in the MkBufferListC
[in]	onlyFirst	Stop after first item was found

MkBufferC* bfl.CheckOptionBUF(MK_STRN opt, MkBufferC* defval = NULL, MK_BOOL onlyFirst = true)

top search for opt in MkBufferListS list and fill var with opt_argument or the defval value … → API: ccmkkernel::MkBufferListC::CheckOptionBUF

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on or MK_NULL
[in]	opt	Find opt string in the MkBufferListC
[in]	defval	The value used if opt was not found
[in]	onlyFirst	If more than one opt is available, return only the first (true [DEFAULT]) or the last (false)
[out]	val_out	If opt is found, return the argument from opt otherwise defval

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

• If val_out is MK_NULL an error is returned.
• If the opt is found but no opt_argument than a error is returned.
• If the opt is found, the opt and the opt_argument are deleted from the MkBufferListC.
• If the defval is returned only a copy of the defval is returned and not the original defval.
• If defval is MK_NULL than an empty MkBufferC is returned.
• (do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
  For details on the out/return value, see: MkKernel_Storage_C_API.

bfl.CheckOptionTT(MK_STRN opt, MK_TT defval = 0, MK_BOOL onlyFirst = true)

top

The BufferListCheckOptionTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	MK_I8	bfl.CheckOptionI8(MK_STRN opt, MK_I8 defval = 0, MK_BOOL onlyFirst = true)	libmkkernel::MkBufferListCheckOptionI8_RT
	MK_I16	bfl.CheckOptionI16(MK_STRN opt, MK_I16 defval = 0, MK_BOOL onlyFirst = true)	libmkkernel::MkBufferListCheckOptionI16_RT
	MK_I32	bfl.CheckOptionI32(MK_STRN opt, MK_I32 defval = 0, MK_BOOL onlyFirst = true)	libmkkernel::MkBufferListCheckOptionI32_RT
	MK_I64	bfl.CheckOptionI64(MK_STRN opt, MK_I64 defval = 0, MK_BOOL onlyFirst = true)	libmkkernel::MkBufferListCheckOptionI64_RT
	MK_STRN	bfl.CheckOptionSTR(MK_STRN opt, MK_STRN defval = "", MK_BOOL onlyFirst = true)	libmkkernel::MkBufferListCheckOptionSTR_RT
	MK_BOOL	bfl.CheckOptionBOL(MK_STRN opt, MK_BOOL defval = false, MK_BOOL onlyFirst = true)	libmkkernel::MkBufferListCheckOptionBOL_RT
	MK_FLT	bfl.CheckOptionFLT(MK_STRN opt, MK_FLT defval = 0, MK_BOOL onlyFirst = true)	libmkkernel::MkBufferListCheckOptionFLT_RT
	MK_DBL	bfl.CheckOptionDBL(MK_STRN opt, MK_DBL defval = 0, MK_BOOL onlyFirst = true)	libmkkernel::MkBufferListCheckOptionDBL_RT

search for opt in MkBufferListS list and fill var with opt_argument or the defval value …

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on or MK_NULL
[in]	opt	Find opt string in the MkBufferListC
[in]	defval	The value used if opt was not found
[in]	onlyFirst	If more than one opt is available, return only the first (true [DEFAULT]) or the last (false)
[out]	val_out	If opt is found, return the argument from opt otherwise defval

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

• If val_out is MK_NULL an error is returned.
• If the opt is found but no opt_argument than a error is returned.
• If the opt is found, the opt and the opt_argument are deleted from the MkBufferListC.
• If the defval is returned only a copy of the defval is returned and not the original defval.

MkBufferListC INDEX

C-API: MkBufferListC_Index_C_API - MkBufferListC - various functions to access a MkBufferListS by index …

bfl.IndexDelete(MK_NUM index, MK_NUM numitems = 1, MK_BOOL doDelete = true)

top delete the index'th list item from the MkBufferListS object … → API: ccmkkernel::MkBufferListC::IndexDelete

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	index	an integer index to access an object in an array by position, start=0, end=-1
	numitems	delete number of items
	doDelete	if doDelete == true delete the MkBufferC object, associated with the index, too

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

MkBufferC* bfl.IndexGet(MK_NUM index)

top get (read only) the index object from bfl … → API: ccmkkernel::MkBufferListC::IndexGet

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	index	an integer index to access an object in an array by position, start=0, end=-1
[out]	val_out	the MkBufferC to return

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

1. val_out is owned by the MkBufferListC and must NOT be freed.
2. val_out will allways be set to MK_NULL first.
3. it is an error if index is not available.

See also

BufferListIndexGetBUF

MkBufferC* bfl.IndexGetBUF(MK_NUM index)

top get the index element from MkBufferListC ... if not available… create it. … → API: ccmkkernel::MkBufferListC::IndexGetBUF

The buffer returned is still owned by bfl.

index	starting	first	next...	mode
+0 < idx < (+)~	begin	0	1, 2, 3 ...	access idx from begin
-1 < idx < (-)~	end	-1	-2, -3, -4 ...	append idx to the end

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	index	an integer index to access an object in an array by position, start=0, end=-1

Returns

the MkBufferC requested

See also

BufferListIndexGet

MK_STRN bfl.IndexGetSTR(MK_NUM index)

top get the index element from MkBufferListC ... as string. … → API: ccmkkernel::MkBufferListC::IndexGetSTR

for details please refer to BufferListIndexGetBUF.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	index	an integer index to access an object in an array by position, start=0, end=-1

Returns

the string requested or an EMPTY-STRING on error

bfl.IndexSet(MK_NUM index, MkBufferC* buf)

top set the index object from bfl … → API: ccmkkernel::MkBufferListC::IndexSet

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	index	an integer index to access an object in an array by position, start=0, end=-1
[in]	buf	the MkBufferS instance to work on

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

It is an error if index is not available.

See also

BufferListIndexSetBUF

bfl.IndexSetBUF(MK_NUM index, MkBufferC* buf)

top set the index element from MkBufferListC ... if not available… createspace … → API: ccmkkernel::MkBufferListC::IndexSetBUF

1. cursize will be >= index+1
2. size will be >= index+1
3. cursize <= X < index+1 -> the missing buffer will be created

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	index	an integer index to access an object in an array by position, start=0, end=-1
[in]	buf	the MkBufferS instance to work on

bfl.IndexSetSTR(MK_NUM index, MK_STRN str)

top set the index element from MkBufferListC ... to string… if not available… create space … → API: ccmkkernel::MkBufferListC::IndexSetSTR

for details please refer to BufferListIndexGetBUF

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	index	an integer index to access an object in an array by position, start=0, end=-1
[in]	str	the string to set

MkBufferC* bfl.IndexExtract(MK_NUM index = 0)

top extract (read & delete) the index object from bfl … → API: ccmkkernel::MkBufferListC::IndexExtract

If the index is not available, this is an error

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	index	an integer index to access an object in an array by position, start=0, end=-1
[out]	val_out	the MkBuffer64S object to return

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

1. val_out is owned by the caller and have to be freed.
2. val_out will allways be set to MK_NULL first.

See also

BufferListDelete

MkBufferListC LOG

C-API: MkBufferListC_Log_C_API - MkBufferListC - various functions to 'log' a MkBufferListS …

bfl.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top write the detail-summary of the MkBufferListC to MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::Log

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

See also

MkBufferListC

bfl.LogS(MK_STRN varname = "bfl", const MkObjectC* fmtobj = NULL, MK_STRN callfunc = __builtin_FUNCTION())

top write the short-summary of the MkBufferListC to MkLogFileC (default: stderr) … → API: ccmkkernel::MkBufferListC::LogS

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
	varname	prefix to identify the variable name
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)

bfl.LogSS(MK_STRN varname = "bfl", const MkObjectC* fmtobj = NULL, MK_STRN callfunc = __builtin_FUNCTION())

top write the very-short-summary of the MkBufferListC to MkLogFileC (default: stderr) … → API: ccmkkernel::MkBufferListC::LogSS

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
	varname	prefix to identify the variable name
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)

bfl.LogSSS(MK_STRN varname = "bfl", const MkObjectC* fmtobj = NULL, MK_STRN callfunc = __builtin_FUNCTION())

top write the very-very-short-summary of the MkBufferListC to MkLogFileC (default: stderr) … → API: ccmkkernel::MkBufferListC::LogSSS

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	varname	The name of the argument to report
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)

MkBufferListC MISC

C-API: MkBufferListC_Misc_C_API - MkBufferListC - various functions to work on a MkBufferListS …

[constructor,static] MkBufferListC* MkBufferListC::FileGlob(MK_STRN pattern_match)

top create a new MkBufferListC using the result from a filesystem glob operation … → API: ccmkkernel::MkBufferListC::FileGlob

to.Move(MkBufferListC* from)

top move all internal data from from to the end of to … → API: ccmkkernel::MkBufferListC::Move

after the move… the from is empty and only the shell exists

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	to	the target of the move
[in]	from	the source of the move

bfl.Copy(const MkBufferListC* src)

top copy all internal data from src to tgt … → API: ccmkkernel::MkBufferListC::Copy

1. existing data will be overwritten
2. the cursize of src will be the cursize of tgt

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	src	the source of the copy

MkBufferListC* bfl.PositionMerge(MkBufferListC* source, MK_NUM position)

top merge a MkBufferListS list into an MkBufferListS object on position … → API: ccmkkernel::MkBufferListC::PositionMerge

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	source	the object to be merged into bfl, afterwords the source is empty and can be deleted
[in]	position	insert in at position, shift all following arguments one up. Set position to 0 to append to the beginning or set position to -1 to append to the end

MK_I32 bfl.Cmp(const MkBufferListC* bfl2)

top compare two buffer-list … → API: ccmkkernel::MkBufferListC::Cmp

First the size is compared and if the size is equal every argument starting from 0 is compared with BufferCmp. The first BufferCmp with a result != 0 finish the comparison and this result is returned.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
[in]	bfl2	buffer-list to compare

Returns

Returns < 0 if bfl is less than bfl2; > 0 if bfl is greater than bfl2, and 0 if they are equal

bfl.Reserve(MK_NUM num)

top reserve num items in a MkBufferListC object … → API: ccmkkernel::MkBufferListC::Reserve

1. cursize will be num
2. size will b >= num
3. free: num <= X < cursize
4. init: cursize <= X < num

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
	bfl	the MkBufferListC object to reserve memory
	num	reserve the number of items for later use.

MkBufferListC* bfl.Reset()

top reset a MkBufferListC object … → API: ccmkkernel::MkBufferListC::Reset

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on

Attention

all MkBufferC objects will be freed

MK_NUM bfl.SearchC(MK_STRN str, MK_NUM len = -1, MK_NUM startindex = 0)

top search libmkkernel::MK_STR item from a MkBufferListS object starting at startindex … → API: ccmkkernel::MkBufferListC::SearchC

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
	str	the string to search for
	len	the length of str or -1 to calulate the length with strlen
	startindex	start searching in buf from index startindex

Returns

The index of the str found or -1 if not found. The return value can be used as startindex of following calls to BufferListSearchC

a typical usage for this code is parsing an MkBufferListS object for multiple occurrences of a string

while ((startindex = MkBufferListSearchC (buf, str, strlen(str), startindex)) != -1) {
  ...
}

Attention

The size of str have to be at least 4 bytes

MK_NUM bfl.Size()

top get the number-of-items in the bfl … → API: ccmkkernel::MkBufferListC::Size

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on

Returns

the number-of-items in the bfl

MkBufferListC* bfl.Sort()

top sort a MkBufferListC … → API: ccmkkernel::MkBufferListC::Sort

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on

Returns

Return the input bfl as sorted list

MkBufferC* bfl.ToBuffer()

top Export a bfl into an MkBufferC using an MkBufferStreamC … → API: ccmkkernel::MkBufferListC::ToBuffer

An buffer is able to hold all primitive types and LIST of primitive types. An buffer-list is an Indexed-LIST representation of a LIST of buffer.

To add a buffer-list into an buffer the buffer-list have to be converted into a buffer-stream and the buffer-stream have to be exported as buffer. The buffer is finally apended to the buffer-list.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on

Returns

the required buffer or a MK_NULL on error

Attention

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MkBufferListC* bfl.ToList()

top get a target-language list representation of the bfl … → API: ccmkkernel::MkBufferListC::ToList

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on

Returns

the required list

Attention

this is only implemented by the Target-Programming-Language (TPL)

MK_STRN bfl.ToString()

top get a string representation of the bfl → API: ccmkkernel::MkObjectC::ToString

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on

Returns

the required string

Attention

• The returned string is owned by self… do not free.
• On error an empty string is returned.

---

MkErrorC

MkErrorC CLASS
		Export	MkErrorC - Export class functions …
		Introspection	MkErrorC - Introspection class functions …
		Misc	MkErrorC - Misc class functions …
MkErrorC TOR
		Delete	Destructor - delete a MkErrorS object …
		Dup	Dup-Constructor - create a new MkErrorC instance as copy from an existing MkErrorC instance …
MkErrorC GET
		GetCode	get the value of MkErrorS::code …
		GetNum	get the MkErrorS::num. The number can be used as exit-code …
		GetSize	get the error-message-size from the exception-object …
		GetText	get the MkErrorS::text …
MkErrorC RAISE
		PanicC	do a panic with string as argument …
		PanicV	do a panic with a vararg as argument …
		PanicVL	do a panic with a vararg-list as argument …
		AppendC	append the message to the MkErrorS::text …
		AppendV	append a vararg string to the MkErrorC …
		AppendVL	append a va_list string to the MkErrorC …
		NoRaise	ignore the next return of libmkkernel::MK_ERROR and do not raise an target-language-exception …
		Raise	convert an ccmkkernel error into an programming-language-error and raise afterwards. …
		SetC	'set' and 'raise' the MkErrorC using a string-message and a errnum-number …
		SetV	set the MkErrorS object using a format string argument list and raise an error …
		SetVL	'set' and 'raise' the MkErrorC using a vararg-list message …
MkErrorC SIGNAL
		IsABORT	check on ABORT signal …
		IsEXIT	check on APPLICATION-EXIT error …
		IsSOCKET	check on SOCKET-DOWN error …
		IsTIMEOUT	check on TIMEOUT error …
		SetABORT	send the ABORT signal to the calling stack…
		SetCode	set the MkErrorS::code value …
		SetCONTINUE	signal end of processing in an MqMqEventIF callback …
		SetEXIT	finish the current callback, return to toplevel and MqExit the application …
		SetSOCKET	create SOCKET-DOWN error …
MkErrorC SYSTEM
		DEFAULT	default-system-error - default-error …
		FORMAT	system-error-format - format and return the default-error …
		IGNORE	ignore-system-error - ignore the next error …
		PRINT	ignore-system-error - print the next error into MkLogFileC …
MkErrorC MISC
		Catch	convert a programming-language-error into an ccmkkernel error …
		Log	log the error to MkLogFileC (default: stderr) …
		Println	print the default-error to the MkLogFileC (default: stderr) and clear the error afterwards …
		Reset	This function clears the err and resets to libmkkernel::MK_OK …
		Stack	check on error and if yes append an ErrorStackFormat to the error-message …
		StackFormat	append an ensemble of func, file and line to the error-message …
		ToString	String-Slot - returns the string representation of the inst …

MkErrorC DETAIL

C-API: MkErrorC_C_API - MkErrorC - the class known as err or error is used to create and manage an error message …

An error is a singleton object per thread created at startup and is located at MkRuntimeRLS using the datatype MkErrorC.

‍As error-indicator the enum libmkkernel::MkErrorE is used.

The MkErrorC is used to collect all data needed to handle an error and provide global ressources required to process and report the error.

The MkErrorC is also used to integrate the error-handling from ccmkkernel into the error-handling-code of the target C++.

Example from Filter6.cc → use MqContextErrorCatch to convert a C++ error into a ccmkkernel error

int MK_CDECL main (int argc, MK_STRN argv[])
{
  MqMsgque::Setup();
  // define factory
  auto Filter6F = MqFactoryCT<Filter6>::Add("Filter6");
  // modify default type
  Filter6F->Type()->fHelp = Filter6::Help;
  // create object from factory
  Filter6 *filter = Filter6F->New();
  try {
    filter->LinkCreate (MkBufferListC {argc, argv});
    filter->ProcessEvent (MQ_WAIT_FOREVER);
  } catch (const exception& e) {
    filter->ErrorCatch(e);
  }
  filter->Exit();
}

MkExceptionC

MkExceptionC - The default-exception of the Programming-Language-Micro-Kernel (PLMK) …

The Programming-Language-Micro-Kernel (PLMK) provide with MkErrorC a complete error-handling with focus to support the "C" Programming-Language. The support include catch, raise, signal and attributes. In addition every Target-Programming-Language (TPL) add their own error-handling and the purpose of MkExceptionC is to integrate the MkErrorC into the Target-Programming-Language (TPL).

The default-exception MkExceptionC is used to connect the MkErrorC with the Target-Programming-Language (TPL) error-object.

• The default-error is defined in MkRuntimeS::error_mk.
• On error the default-error is set to the error-data, the MkErrorE status change to libmkkernel::MK_ERROR.
• The non-C language create a copy from the default-error and throw the copy as MkExceptionC exception.
• The C language just return the MkErrorE status of the default-error.

The implementation of an exception depends heavily on the Target-Programming-Language (TPL), starting with no exception at all, for example. C, an exception as a class object, or as an exception as a global attribute.

Attention

• All MkExceptionC code is implemented at the Target-Programming-Language (TPL) without support by the Programming-Language-Micro-Kernel (PLMK) compiler.
• By default, MkExceptionC is only used internally, hidden by the class MkErrorC.

ExceptionCheck

Checks if Exception is of type MkExceptionC and returns true or false …

Example: test case to check KILL and RECOVER feature, check on MkExceptionC

            MK_I32 PID, RET=0;
            auto VAL = ReadBUF();
            Client cl;
            cl.LinkCreate(ConfigGetStartAs());
            cl.Send("W","GPID@I", &PID);
            SysKill(PID,9);
            for (int i = 0; i < 3; i++) {
              try {
                cl.Send("W","ECOI:U@I", VAL, &RET);
              } catch (const MkExceptionC &ex) {
                auto err = cl.ErrorCatch(ex);
                if (err->IsSOCKET()) {
                  err->Reset();
                  cl.LinkConnect();
                  continue;
                } else {
                  err->Raise();
                }
              }
              break;
            }
            SendSTART();
            SendI32(RET);

Returns

the result of the check, true or false

Parameters

[in]

exception

the exception object from C++, if MK_NULL the global exception object is used

MkErrorC CLASS

NAVI: top, up

MkErrorC CLASS EXPORT

		HandleResolve	Handle-Resolve-Slot - return a MkErrorC from netHdl or MK_NULL if invalid…
		HandleGet	Handle-Get-Slot - returns a export-hdl to the MkErrorC useable for external storage

MkErrorC CLASS INTROSPECTION

		Instances	get head-instance from linked-list of MkErrorS type …
		Next	get next instance from linked-list of MkErrorS type
		Prev	get previous instance from linked-list of MkErrorS type

MkErrorC CLASS MISC

GetNull

Null-Slot - return a MkErrorC typed NULL instance …

MkErrorC CLASS DETAILS

C-API: MkErrorC_Class_C_API - MkErrorC - define the class …

MkErrorC CLASS EXPORT

MkErrorC - Export class functions …

[static] MkErrorC* MkErrorC::HandleResolve(MK_HDL netHdl)

top Handle-Resolve-Slot - return a MkErrorC from netHdl or MK_NULL if invalid… → API: ccmkkernel::MkErrorC::HandleResolve

The MkErrorHandleResolve undo the MkErrorHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	netHdl	handle former exported with MkErrorHandleGet

Returns

the required handle or MK_NULL if netHdl is invalid

MK_HDL err.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkErrorC useable for external storage → API: ccmkkernel::MkObjectC::HandleGet

The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MkErrorHandleResolve.

By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.

The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.

example: The export-hdl is used in rpc to identify an object across the network.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)

Returns

the required export-hdl

MkErrorC CLASS INTROSPECTION

MkErrorC - Introspection class functions …

[static] MkErrorC* MkErrorC::Instances()

top get head-instance from linked-list of MkErrorS type … → API: ccmkkernel::MkErrorC::Instances

The head-instance is the last instance created.

MkErrorC* err.Next()

top get next instance from linked-list of MkErrorS type → API: ccmkkernel::MkErrorC::Next

MkErrorC* err.Prev()

top get previous instance from linked-list of MkErrorS type → API: ccmkkernel::MkErrorC::Prev

MkErrorC CLASS MISC

MkErrorC - Misc class functions …

[static] MkErrorC* MkErrorC::GetNull()

top Null-Slot - return a MkErrorC typed NULL instance … → API: ccmkkernel::MkErrorC::GetNull

MkErrorC TOR

C-API: MkErrorC_TOR_C_API - MkErrorC - various functions to 'create' and 'delete' a MkErrorS …

[destructor] err.Delete()

top Destructor - delete a MkErrorS object … → API: libmkkernel::MkErrorDelete_RT

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. The internal memory will be freed and the object-pointer will be set to NULL. If the object-pointer is already NULL nothing will be done.
2. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
3. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
4. After a SOFT-delete, the outher shell is still alive, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.
5. On HARD-delete read more at MkSelfDeleteForce

See also

BufferDup ObjectDelete

[constructor] MkErrorC* srce.Dup()

top Dup-Constructor - create a new MkErrorC instance as copy from an existing MkErrorC instance … → API: ccmkkernel::MkErrorC::Dup

The new instance belongs to the caller and may have to be released if necessary. A manual release using ErrorDelete is always possible, but the instance can no longer be used afterwards.

Returns

The newly created MkErrorC instance, the instance is owned by the caller

See also

MkObjDup MkErrorDelete

MkErrorC GET

C-API: MkErrorC_Get_C_API - MkErrorC - various functions to 'get' data out of a MkErrorS …

MkErrorE err.GetCode()

top get the value of MkErrorS::code … → API: ccmkkernel::MkErrorC::GetCode

MK_I32 err.GetNum()

top get the MkErrorS::num. The number can be used as exit-code … → API: ccmkkernel::MkErrorC::GetNum

MK_SIZE err.GetSize()

top get the error-message-size from the exception-object … → API: ccmkkernel::MkErrorC::GetSize

MK_STRN err.GetText()

top get the MkErrorS::text … → API: ccmkkernel::MkErrorC::GetText

MkErrorC RAISE

C-API: MkErrorC_Raise_C_API - MkErrorC - various functions to 'raise' a MkErrorS …

An error is "raised" by naming the MkErrorS::text and changing the MkErrorS::code to libmkkernel::MK_ERROR.

[static] MkErrorC::PanicC(const MkObjectC* errfmt, MK_STRN callfunc, MK_I32 errnum, MK_STRN message)

top do a panic with string as argument … → API: ccmkkernel::MkErrorC::PanicC

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errfmt	a managed object used to identify and format the error-message
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	errnum	the error number used as exit-code as well
	message	the string to be displayed

Attention

this function will never return

[static] MkErrorC::PanicV(const MkObjectC* errfmt, MK_STRN callfunc, MK_I32 errnum, MK_FST printfmt, ... )

top do a panic with a vararg as argument … → API: ccmkkernel::MkErrorC::PanicV

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errfmt	a managed object used to identify and format the error-message
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	errnum	the error number used as exit-code as well
[in]	printfmt	is a c-string used as printf like format string

Attention

this function will never return

[static] MkErrorC::PanicVL(const MkObjectC* errfmt, MK_STRN callfunc, MK_I32 errnum, MK_FST printfmt, va_list var_list)

top do a panic with a vararg-list as argument … → API: ccmkkernel::MkErrorC::PanicVL

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errfmt	a managed object used to identify and format the error-message
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	errnum	the error number used as exit-code as well
[in]	printfmt	is a c-string used as printf like format string
[in]	var_list	a variable argument list object

Attention

this function will never return

err.AppendC(MK_STRN message)

top append the message to the MkErrorS::text … → API: ccmkkernel::MkErrorC::AppendC

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	message	the string to be displayed as message (append)

err.AppendV(MK_FST printfmt, ... )

top append a vararg string to the MkErrorC … → API: ccmkkernel::MkErrorC::AppendV

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	printfmt	is a c-string used as printf like format string

err.AppendVL(MK_FST printfmt, va_list var_list)

top append a va_list string to the MkErrorC … → API: ccmkkernel::MkErrorC::AppendVL

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	printfmt	is a c-string used as printf like format string
[in]	var_list	a variable argument list object

MkErrorC* err.NoRaise()

top ignore the next return of libmkkernel::MK_ERROR and do not raise an target-language-exception … → API: ccmkkernel::MkErrorC::NoRaise

Many functions from the MkErrorXXX return an MkErrorE to signal that an libmkkernel::MK_ERROR is set. The target-language react on this signal and raise an target-language-exception.
If this behaviour is not desired the ErrorNoRaise is used to suppress the next libmkkernel::MK_ERROR return.

This feature is used to avoid the target-language-exception after ErrorSetC etc.

This is usefull if:

1. an error should be send by MqSendERROR later
2. an error will be extended by using multiple ErrorAppendC etc later and than raised with ErrorRaise

Example from server.cc → create and send an background-error message

      void BgError () {
	MqContextC *master = SlaveGetMaster();
	if (master != NULL) {
          auto err = master->ErrorFORMAT()->NoRaise();
	  err->SetC (err->GetText(), "BGERROR", err->GetNum());
	  master->SendERROR();
	}
      }

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)

Returns

the input err with MkErrorS::noRaise flag set

err.Raise()

top convert an ccmkkernel error into an programming-language-error and raise afterwards. … → API: ccmkkernel::MkErrorC::Raise

If ther is no ccmkkernel-error (MkErrorS::code "= #libmkkernel::MK_ERROR) than nothing happen. @param [in] err the \ref libmkkernel::MkErrorS "MkErrorS" instance to work on - the \e default-error is automatically created on startup. (NULL allowed) \sa \ref doc_mk_cc_ErrorCatch "ErrorCatch" \ref doc_mk_cc_ErrorReset "ErrorReset"

err.SetC(MK_STRN message, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 errnum = -1)

top 'set' and 'raise' the MkErrorC using a string-message and a errnum-number … → API: ccmkkernel::MkErrorC::SetC

The message will be formatted into a ccmkkernel error-message.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed) - err==NULL allowed
[in]	message	the string to be displayed as message
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	errnum	the error number used as exit-code as well

Attention

Use ErrorNoRaise to avoid raise an error.

err.SetV(MK_STRN callfunc, MK_I32 errnum, MK_FST printfmt, ... )

top set the MkErrorS object using a format string argument list and raise an error … → API: ccmkkernel::MkErrorC::SetV

The string argument list will be formatted into a ccmkkernel error-message.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	errnum	the error number used as exit-code as well
[in]	printfmt	is a c-string used as printf like format string

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

Use ErrorNoRaise to avoid raise an error.

err.SetVL(MK_STRN callfunc, MK_I32 errnum, MK_FST printfmt, va_list var_list)

top 'set' and 'raise' the MkErrorC using a vararg-list message … → API: ccmkkernel::MkErrorC::SetVL

The var_list will be formatted into a ccmkkernel error-message.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	errnum	the error number used as exit-code as well
[in]	printfmt	is a c-string used as printf like format string
[in]	var_list	a variable argument list object

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

Use ErrorNoRaise to avoid raise an error.

MkErrorC SIGNAL

C-API: MkErrorC_Signal_C_API - MkErrorC - various functions to set and check a 'signal' on a MkErrorS …

MK_BOOL err.IsABORT()

top check on ABORT signal … → API: ccmkkernel::MkErrorC::IsABORT

MK_BOOL err.IsEXIT()

top check on APPLICATION-EXIT error … → API: ccmkkernel::MkErrorC::IsEXIT

The exit-error-object is made for two resons:

1. The error is set by ErrorSetEXIT to signal end-of-application.
2. The error is raised by a function to signal a fatal-error which require an application-exit.
   The only source of this kind of fatal-error is a link-target-abnormal-exit caused by a server/network crash.

The link-target-abnormal-exit can only occur for functions that perform a network-request, such as:

• MqLinkCreate, MqLinkCreateChild, MqLinkConnect, MqSendEND, MqSendEND_AND_WAIT or MqProcessEvent

The aim of this function is to react to an exit-error-object and is used to ignore the error with an ErrorReset and then later to re-establish a connection with a MqLinkConnect.

• Read more from the: example//Filter4.cc example

Example "C": catch and ignore an EXIT return-code

if (MkErrorCheckI (MqSendEND_AND_WAIT (ctx, "TOKS", MK_TIMEOUT_USER))) {
  if (MkErrorIsEXIT_0E ()) MkErrorReset_1X (ctx);
}

MK_BOOL err.IsSOCKET()

top check on SOCKET-DOWN error … → API: ccmkkernel::MkErrorC::IsSOCKET

MK_BOOL err.IsTIMEOUT()

top check on TIMEOUT error … → API: ccmkkernel::MkErrorC::IsTIMEOUT

err.SetABORT(MK_STRN detail = "UNKNOWN", MK_STRN callfunc = __builtin_FUNCTION())

top send the ABORT signal to the calling stack… → API: ccmkkernel::MkErrorC::SetABORT

The ABORT-signal is used to disrupt the current execution like an error and unwind the calling stack. The MkErrorIsABORT is used to detect the ABORT-signal and MkErrorReset is used to clear the ABORT-signal

err.SetCode(MkErrorE code)

top set the MkErrorS::code value … → API: ccmkkernel::MkErrorC::SetCode

err.SetCONTINUE()

top signal end of processing in an MqMqEventIF callback … → API: ccmkkernel::MkErrorC::SetCONTINUE

err.SetEXIT(MK_STRN callfunc = __builtin_FUNCTION())

top finish the current callback, return to toplevel and MqExit the application … → API: ccmkkernel::MkErrorC::SetEXIT

To exit a application in a callback is a difficult task because the code is in-duty. To achieve this goal a special exit-error-object is created and reported to the toplevel. If a transaction is ongoing the MqSendRETURN is not called and thus the transaction is not finished. The calling application is informed later by a socket-down event. This only works for a parent-context. An exit in a child-context is ignored.

Example: raise an EXIT-exception in an ruby-service:

def EXIT
  MkErrorC.DEFAULT().SetEXIT()
end

err.SetSOCKET(MK_STRN detail = "UNKNOWN", MK_STRN callfunc = __builtin_FUNCTION())

top create SOCKET-DOWN error … → API: ccmkkernel::MkErrorC::SetSOCKET

MkErrorC SYSTEM

C-API: MkErrorC_System_C_API - MkErrorC - various functions to raise a 'System' messagen on MkErrorS …

[static] MkErrorC* MkErrorC::DEFAULT()

top default-system-error - default-error … → API: ccmkkernel::MkErrorC::DEFAULT

The default-error is defined once per runtime and is used as only-valid-source of an MkErrorC in a thread or process.

See also

ErrorFORMAT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

[static] MkErrorC* MkErrorC::FORMAT(const MkObjectC* fmtobj = NULL)

top system-error-format - format and return the default-error … → API: ccmkkernel::MkErrorC::FORMAT

Returns

the MkErrorS::format_of_error or MkErrorS::source_of_error attribute

MkErrorFORMAT - usage

Set the MkErrorS::format_of_error attribute to fmtobj or MK_NULL. The next error-message will be formated as usual and than be raised as error. The default-error will be modified.

The next error-message created with ErrorSetC etc is formatted with MkRuntimeS->cid ("context-in-duty") or simply as "DEFAULT" if cid == NULL.

Parameters

[in]

fmtobj

managed object used to format the log-message (default=MK_NULL → use default-format)

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

[static] MkErrorC* MkErrorC::IGNORE()

top ignore-system-error - ignore the next error … → API: ccmkkernel::MkErrorC::IGNORE

The next error will be ignored, no formatting will be performed and the the default-error will not be modified.

MkErrorIGNORE - usage

There are two functions to suppress an error: MkErrorIGNORE and MkErrorNoRaise.

MkErrorIGNORE

Set the MkErrorS::format_of_error attribute to IGNORE. The next error will be ignored, no formatting will be performed and the the default-error will not be modified.

MkErrorNoRaise

Set the MkErrorS::noRaise attribute to TRUE. The next error will be set as usual but not raised. This is usefull to set an error and later append additional information to the error. Final the error have to be raised with MkErrorRaise.

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

[static] MkErrorC* MkErrorC::PRINT()

top ignore-system-error - print the next error into MkLogFileC … → API: ccmkkernel::MkErrorC::PRINT

The next error-message will be formated as usual and than be reported using MkLogVL. The default-error will not be modified.

MkErrorPRINT - usage

Set the MkErrorS::format_of_error attribute to PRINT.

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

MkErrorC MISC

C-API: MkErrorC_Misc_C_API - MkErrorC - various functions to 'work' on a MkErrorS …

MkErrorC* err.Catch(std::exception* exception = NULL, MK_STRN callfunc = __builtin_FUNCTION())

top convert a programming-language-error into an ccmkkernel error … → API: ccmkkernel::MkErrorC::Catch

Same as MkObjectErrorCatch but skip the Error-Prefix in final Target-Programming-Language (TPL).

Example from Bug3.cc → catch an error using MkErrorC* err.Catch(std::exception* exception = NULL, MK_STRN callfunc = __builtin_FUNCTION())

  } catch (const std::exception& ex) {
    MkErrorC::DEFAULT()->Catch(ex)->Println();
  } catch (...) {
    MkErrorC::PRINT()->SetC("unknown exception");
  }

Note

The C language does not support the MkErrorCatch because there is no native error object.

If there is no error at all the MkErrorCatch does nothing and just return the MkErrorDEFAULT.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	exception	the exception object from C++, if MK_NULL the global exception object is used
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)

Returns

the ErrorDEFAULT initialized with exception value

See also

ObjectErrorCatch ErrorRaise ErrorReset

err.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top log the error to MkLogFileC (default: stderr) … → API: ccmkkernel::MkObjectC::Log

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

See also

MkErrorC err.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

err.Println()

top print the default-error to the MkLogFileC (default: stderr) and clear the error afterwards … → API: ccmkkernel::MkErrorC::Println

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)

err.Reset(MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 callline = __builtin_LINE(), MK_BOOL force = false)

top This function clears the err and resets to libmkkernel::MK_OK … → API: ccmkkernel::MkErrorC::Reset

Attention

Use this function carfully, as misuse will result in the loss of the error-message.

It is recommended that you use this feature only after the error has been processed.

• processed = The error was send to another server or printed to the user or to a file.

See also

ErrorRaise ErrorCatch

MkErrorE err.Stack(MK_STRN callfunc = __builtin_FUNCTION(), MK_STRN callfile = __builtin_FILE(), MK_I32 callline = __builtin_LINE())

top check on error and if yes append an ErrorStackFormat to the error-message … → API: ccmkkernel::MkErrorC::Stack

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed) → MK_NULL allowed
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	callfile	the name of the file the call take place (e.g. FILE)
[in]	callline	the number of the line the call take place (e.g. LINE)

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

err.StackFormat(MK_STRN callfunc = __builtin_FUNCTION(), MK_STRN callfile = __builtin_FILE(), MK_I32 callline = __builtin_LINE())

top append an ensemble of func, file and line to the error-message … → API: ccmkkernel::MkErrorC::StackFormat

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	callfile	the name of the file the call take place (e.g. FILE)
[in]	callline	the number of the line the call take place (e.g. LINE)

MK_STRN inst.ToString()

top String-Slot - returns the string representation of the inst … → API: ccmkkernel::MkObjectC::ToString

The string is a human-readable form of the data stored in the object.

See also

slot: every class should provide a ToString function by default.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	inst	- the instance to work on

Returns

the requested string or "MK_NULL" on error

Note

(do not free) The memory of the out/return value belongs to the called ccmkkernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

---

MkLogFileC

MkLogFileC CLASS
		Export	MkLogFileC - Export class functions …
		Introspection	MkLogFileC - Introspection class functions …
		Misc	MkLogFileC - Misc class functions …
MkLogFileC TOR
		Open	open the log-file in append mode …
		Close	Destructor - delete a MkLogFileC instance …
MkLogFileC WRITE
		GetFile	get the log-file …
		WriteC	write to log-file …
		WriteV	write to log-file …
		WriteVL	write to log-file …

MkLogFileC DETAIL

C-API: MkLogFileC_C_API - MkLogFileC - the class known as lfl or log-file is used to control the target of the logging-output …

The logging-target is set direct by RuntimeSetLogfile or using the class MkLogFileC.

The target is stored at the MkRuntimeC using a FILE-stream and can be set individually for each thread. The default is stderr.

• the handle is stored at MkRuntimeS::logFILE
• the filename (if available) is stored at MkRuntimeS::logfile

possible values are:

value	decription	OS man-page
stdout	the standart output	stdio(3)
stderr	the standart error output	stdio(3)
fileName	an arbitary fileName	fopen(3)

MkLogFileC CLASS

NAVI: top, up

MkLogFileC CLASS EXPORT

		HandleResolve	Handle-Resolve-Slot - return a MkLogFileC from netHdl or MK_NULL if invalid…
		HandleGet	Handle-Get-Slot - returns a export-hdl to the MkLogFileC useable for external storage

MkLogFileC CLASS INTROSPECTION

		Instances	get head-instance from linked-list of MkLogFileS type …
		Next	get next instance from linked-list of MkLogFileS type
		Prev	get previous instance from linked-list of MkLogFileS type

MkLogFileC CLASS MISC

GetNull

Null-Slot - return a MkLogFileC typed NULL instance …

MkLogFileC CLASS DETAILS

C-API: MkLogFileC_Class_C_API - MkLogFileC - define the class …

MkLogFileC CLASS EXPORT

MkLogFileC - Export class functions …

[static] MkLogFileC* MkLogFileC::HandleResolve(MK_HDL netHdl)

top Handle-Resolve-Slot - return a MkLogFileC from netHdl or MK_NULL if invalid… → API: ccmkkernel::MkLogFileC::HandleResolve

The MkLogFileHandleResolve undo the MkLogFileHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	netHdl	handle former exported with MkLogFileHandleGet

Returns

the required handle or MK_NULL if netHdl is invalid

MK_HDL lfl.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkLogFileC useable for external storage → API: ccmkkernel::MkObjectC::HandleGet

The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MkLogFileHandleResolve.

By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.

The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.

example: The export-hdl is used in rpc to identify an object across the network.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	lfl	the MkLogFileS instance to work on

Returns

the required export-hdl

MkLogFileC CLASS INTROSPECTION

MkLogFileC - Introspection class functions …

[static] MkLogFileC* MkLogFileC::Instances()

top get head-instance from linked-list of MkLogFileS type … → API: ccmkkernel::MkLogFileC::Instances

The head-instance is the last instance created.

MkLogFileC* lfl.Next()

top get next instance from linked-list of MkLogFileS type → API: ccmkkernel::MkLogFileC::Next

MkLogFileC* lfl.Prev()

top get previous instance from linked-list of MkLogFileS type → API: ccmkkernel::MkLogFileC::Prev

MkLogFileC CLASS MISC

MkLogFileC - Misc class functions …

[static] MkLogFileC* MkLogFileC::GetNull()

top Null-Slot - return a MkLogFileC typed NULL instance … → API: ccmkkernel::MkLogFileC::GetNull

MkLogFileC TOR

C-API: MkLogFileC_TOR_C_API - MkLogFileC - various functions to 'create and delete' a MkLogFileS …

[constructor,static] MkLogFileC* MkLogFileC::Open(MkObjectC* errfmt, MK_STRN file)

top open the log-file in append mode … → API: ccmkkernel::MkLogFileC::Open

The new instance belongs to the caller and may have to be released if necessary. A manual release using LogFileClose is always possible, but the instance can no longer be used afterwards.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errfmt	a managed object used to identify and format the error-message
[in]	file	the filename to open
[out]	lfh_out	returns

Returns

The newly created MkLogFileC instance, the instance is owned by the caller

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Attention

on error the lfh_out is set to MK_NULL

[destructor] lfh.Close()

top Destructor - delete a MkLogFileC instance … → API: libmkkernel::MkLogFileClose_RT

There are two different ways to delete an instance:

ObjectDispose	to free the internal data but keep the outher shell alive - this is called a SOFT-DELETE
ObjectDelete	to delete the outher shell including the internal data - this is called a HARD-DELETE

Attention

1. The internal memory will be freed and the object-pointer will be set to NULL. If the object-pointer is already NULL nothing will be done.
2. For a programming language without HARD-Delete support, the "Delete" method is assigned to a SOFT-Delete.
3. For a programming language without garbage collection, a SOFT-delete without a HARD-delete causes a small memory loss (C++: ~32 bytes).
4. After a SOFT-delete, the outher shell is still alive, but cannot be used. Any access to this shell generates an HDL-null-exception, but this exception can be caught. This is important for C++ as it prevents a core dump.
5. On HARD-delete read more at MkSelfDeleteForce

See also

LogFileOpen

MkLogFileC WRITE

C-API: MkLogFileC_Write_C_API - MkLogFileC - various functions to 'write' into a MkLogFileS …

MK_STRN lfl.GetFile()

top get the log-file … → API: ccmkkernel::MkLogFileC::GetFile

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	lfl	the MkLogFileS instance to work on
[out]	file_out	the log-file to return

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

lfl.WriteC(MK_STRN text)

top write to log-file … → API: ccmkkernel::MkLogFileC::WriteC

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	lfl	the MkLogFileS instance to work on
[in]	text	the text to write

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

lfl.WriteV(MK_FST printfmt, ... )

top write to log-file … → API: ccmkkernel::MkLogFileC::WriteV

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	lfl	the MkLogFileS instance to work on
[in]	printfmt	is a c-string used as printf like format string

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

lfl.WriteVL(MK_FST printfmt, va_list var_list)

top write to log-file … → API: ccmkkernel::MkLogFileC::WriteVL

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	lfl	the MkLogFileS instance to work on
[in]	printfmt	is a c-string used as printf like format string
[in]	var_list	a variable argument list object

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

---

MkRuntimeC

MkRuntimeC CONFIG
		GetDebug	get the MkRuntimeS::debug value …
		GetErrorCode	return libmkkernel::MkErrorS::code from a given MkRuntimeC …
		GetIsSilent	get the MkRuntimeS::isSilent value …
		GetLogfile	get the MkRuntimeS::logfile value …
		SetDebug	set the MkRuntimeS::debug value …
		SetIsSilent	set the MkRuntimeS::isSilent value …
		SetLogfile	set the MkRuntimeS::logfile value and cleanup old value …
MkRuntimeC INFO
		Log	log the MkRuntimeC …

MkRuntimeC DETAIL

C-API: MkRuntimeC_C_API - 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

MkRuntimeC CONFIG

C-API: MkRuntimeC_Config_C_API - MkRuntimeC - various functions to configure the MkRuntimeRLS (only C) …

The MkRuntimeRLS-configuration belongs to a single MkRuntimeRLS. In a threadable application, each thread has its own MkRuntimeRLS and therefore its own configuration.

A function ending in 'I' is the inline variant of the function without the 'I' and is preferred in C.

[static] MK_I32 MkRuntimeC::GetDebug()

top get the MkRuntimeS::debug value … → API: ccmkkernel::MkRuntimeC::GetDebug

[static] MkErrorE MkRuntimeC::GetErrorCode()

top return libmkkernel::MkErrorS::code from a given MkRuntimeC … → API: ccmkkernel::MkRuntimeC::GetErrorCode

[static] MK_BOOL MkRuntimeC::GetIsSilent()

top get the MkRuntimeS::isSilent value … → API: ccmkkernel::MkRuntimeC::GetIsSilent

[static] MK_STRN MkRuntimeC::GetLogfile()

top get the MkRuntimeS::logfile value … → API: ccmkkernel::MkRuntimeC::GetLogfile

Attention

the string is owned by ccmkkernel -> do not free !!

[static] MkRuntimeC::SetDebug(MK_I32 dbg)

top set the MkRuntimeS::debug value … → API: ccmkkernel::MkRuntimeC::SetDebug

[static] MkRuntimeC::SetIsSilent(MK_BOOL silent)

top set the MkRuntimeS::isSilent value … → API: ccmkkernel::MkRuntimeC::SetIsSilent

[static] MkRuntimeC::SetLogfile(MK_STRN logfile)

top set the MkRuntimeS::logfile value and cleanup old value … → API: ccmkkernel::MkRuntimeC::SetLogfile

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	logfile	filename, "stdout" or "stderr", default = "stderr" for MK_NULL or ""

MkRuntimeC INFO

C-API: MkRuntimeC_Info_C_API - MkRuntimeC - various functions to print information about the rt …

rt.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0)

top log the MkRuntimeC … → API: ccmkkernel::MkObjectC::Log

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	rt	The runtime to log, (default=MK_NULL → use the doc_mk_cc_runtime-default)
[in]	fmtobj	managed object used to format the log-message (default=MK_NULL → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

See also

MkRuntimeC

---

BINARY OBJECT

No special binary-object is used. All binary-data is available as C++ MK_BINN.

---

EXAMPLES

Example from server.cc → read a buffer-object and convert single-char-type-identifer to string.

      void BUF2 () {
	SendSTART();
	for (int i=0; i<3; i++) {
          // using a reference or a pointer to avoid a "copy", ReadBUF never return NULL
	  const MkBufferC& buf = *ReadBUF();
          // GetType3 is "const", return the type as "string"
	  SendSTR(buf.GetType3());
	  SendBUF(buf);
	}
	SendRETURN();
      }

---

SEE ALSO

libmkkernel, ccmkkernel, csmkkernel, javamkkernel, gomkkernel, pymkkernel, rbmkkernel, tclmkkernel, perlmkkernel, phpmkkernel

KEYWORDS

C++, unix, socket, message, msgque