libmkkernel

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

SYNOPSIS

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

• link: -Lpath -lmkkernel or automake: LDADD = libmkkernel.la

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

object	description
Mk	the namespace with all libmkkernel specific definitions
MkAttribute(…)	the interface to access the package specific attribute
MkClassAttribute(…)	the interface to access the class specific attribute
MkClassAttribute(Instance,…)	the interface to access the instance specific attribute

To access all features without Mk prefix use:

• #include "kernel_mk.h"

Using the libmkkernel package ...

C package libraries

liblibmkkernel.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.
liblibmkkernel.la	A .la file is a text file used by the GNU libtools package to describe the files that make up the corresponding library.

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

> LDADD = path/to/liblibmkkernel.la

or

> mylib_la_LIBADD = path/to/liblibmkkernel.la

Example from acmds/Makefile.am using libmkkernel.la and libmqmsgque.la:

 
atool_SOURCES   = atool.c ajoin.c acut.c asort.c asplit.c optionL.c optionL.h
atool_CPPFLAGS  = $(libmqmsgque_CPPFLAGS)
atool_CFLAGS    = $(libmqmsgque_CFLAGS)
atool_LDFLAGS   = @noversion_LDFLAGS@
atool_LDADD     = $(libmqmsgque_LIBADD_shared)
 

---

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 a target language.

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 libmkkernel 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 libmkkernel package is loaded with:

‍link: -Lpath -lmkkernel or automake: LDADD = libmkkernel.la

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

The libmkkernel package add the following public classes into MkObjectC_C_API :

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

The libmkkernel 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 …

libmkkernel is also called as Programming-Language-Micro-Kernel (PLMK). libmkkernel 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 libmkkernel 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 libmkkernel-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 MK_YES or MK_NO
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	MK_BUF	buffer-item that can hold any single typed item from above
BFL	L	MK_BFL	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	MK_BIN	MK_BINN	byte-array pointer data-type with binary encoding (MK_BINN)
STR	C	MK_STR	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 libmkkernel to provide temporary storage. It is a common design pattern that libmkkernel 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 libmkkernel 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 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 libmkkernel 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.c → "ReadBFL" overwrite previous "ReadBFL"

static enum MkErrorE Ot_BFL2 ( MQ_SERVICE_CALL_ARGS )
{
  MK_BFL tmp1 = MqReadBFL_e(mqctx);                           // "tmp1" is now a reference to the FLS storage of "ReadBFL"
  MK_BFL tmp2 = MqReadBFL_e(mqctx);                           // ERROR: the "tmp2" is using a SHARED reference with "tmp1"
  MqSend_E(mqctx, "R", "LL", tmp1, tmp2);                   // ERROR: "$tmp1" and "$tmp2" are the SAME values
  return MK_OK;
error:
  return MqSendRETURN (mqctx);
}

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

static enum MkErrorE pBFL3 ( MQ_SERVICE_CALL_ARGS ) {
  __attribute__((unused))
  MK_BFL tmp2 = MqReadBFL_e(mqctx);                           // ERROR: the "tmp2" is using a SHARED reference with "tmp1"
  return MK_OK;
error:
  return MkErrorStack_1X(mqctx);
}
static enum MkErrorE Ot_BFL3 ( MQ_SERVICE_CALL_ARGS )
{
  MK_BFL tmp1 = MqReadBFL_e(mqctx);                           // "tmp1" is now a reference to the FLS storage of "ReadBFL"
  MqSend_E(mqctx, "C", pBFL3, "ECOL:[III]", 4, 5, 6);       // ATTENTION: callback "pBFL3" using "ReadBFL"
  MqProcessEvent_E(mqctx,MQ_WAIT_OWN,MK_TIMEOUT_DEFAULT);   // ERROR: enter event-loop, callback "pBFL3" is called
  MqSend_E(mqctx, "R", "L", tmp1);                          // ERROR: "tmp1" has now the value from "tmp2"
  return MK_OK;
error:
  return MqSendRETURN (mqctx);
}

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

static enum MkErrorE Ot_BFL4 ( MQ_SERVICE_CALL_ARGS )
{
  MK_BFL tmp1 = MqReadBFL_e(mqctx);                           // "tmp1" is now a reference to the FLS storage of "ReadBFL"
  MK_BFL glb1 = MkBufferListDup(tmp1);                      // OK: "glb1" is now a UNSHARED reference to the global memory
  MK_BFL tmp2 = MqReadBFL_e(mqctx);                           // "tmp2" is now a reference to the FLS storage of "ReadBFL"
  MqSend_E(mqctx, "R", "LL", glb1, tmp2);                   // OK: "glb1" (alias tmp1) and "tmp2" are separate references
  MkBufferListDelete(glb1);                                 // ATTENTION: don't forget to free the global memory in C
  return MK_OK;
error:
  return MqSendRETURN (mqctx);
}

TLS storage 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 tlsid (0,1,2,3...) 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

1. Use the *CreateTLS style function with caution in a local (controlled) context.
2. It is a good-practice to manage the tlsid on a global level like an enum
3. 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.c → performance test with TLS storage in a local (controlled) context

static enum MkErrorE
Ot_BUST ( MQ_SERVICE_CALL_ARGS )
{
  MK_BUS bus = MkBufferStreamCreateTLS_1( "perfserver-BUST" );

  while (MqReadItemExists(mqctx)) {
    MkBufferStreamWriteBUF(bus,MqReadBUF_e(mqctx));
  }

  MkBufferStreamPosToStart(bus);

  MqSendSTART_E (mqctx);
  while (MkBufferStreamReadItemExists(bus)) {
    MqSendBUF_E (mqctx, MkBufferStreamReadBUF_e (bus));
  }

error:
  return MqSendRETURN (mqctx);
}

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 libmkkernel …
MkKernel ENUM
		enum MkTypeE	basic data-types supported by Programming-Language-Micro-Kernel (PLMK) …
		enum MkTimeoutE	Predefined Timeout values …
		enum MkErrorE	collection for the different error-codes …
MkKernel BINARY
		BinaryCreate	create a binary from data and size ...
		BinaryCreateSlice	create a binary slice ...
		BinaryDataGet	get data pointer from the binary ...
		BinaryDup	create a binary as duplicate from an already existsing MkBinaryR ...
		BinaryIsNull	check if binary is NULL ...
		BinaryLog	log the binary ...
		BinarySizeGet	get size from the binary ...
MkKernel STRING
		StringCreate	create a str from ptr and len ...
		StringCreate_1	create a str from ptr use MK_NULL as end-of-string ...
		StringDataGet	get ptr pointer from the string ...
		StringDup	create a string as duplicate from an already existsing MkBinaryR ...
		StringIsNULL	check if strR is MK_NULL_STR return true or false …
		StringLogI	log the string ...
		StringSizeGet	get len from the string ...
		StringSlice	create a slice of strR start at start with max len bytes …
		StringSplit	split a str into ptr and len …

MkKernel DETAIL

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

The libmkkernel package is loaded with:

‍link: -Lpath -lmkkernel or automake: LDADD = libmkkernel.la

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

The libmkkernel package add the following public classes into MkObjectC_C_API :

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

The libmkkernel 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 libmkkernel internal memory …
		Setup	setup libmkkernel internal memory …

MkKernel SETUP DETAILS

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

Initializing a libmkkernel library depends on the target language and the specific nature of the Programming-Language-Micro-Kernel (PLMK).

In general it is required to call a Setup style funtion as FIRST argument 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 libmkkernel 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 libmkkernel 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 libmkkernel library must be known when the thread starts. This is not a problem as long as the external libmkkernel library is linked to the application. However, if dlopen is used to load the libmkkernel library, the current restriction is that the new data type from the libmkkernel 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) void MkCleanup()

top cleanup libmkkernel internal memory … → API: MkCleanup

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) void MkSetup()

top setup libmkkernel internal memory … → API: MkSetup

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 MkErrorE

top collection for the different error-codes … → API: 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) enum MkErrorE MkErrorE_FromInt(MK_I32 const value, enum MkErrorE *value_out)

top return the MkErrorE from integer … → API: MkErrorE_FromInt

(static) MK_I32 MkErrorE_ToInt(enum MkErrorE value)

top return the MkErrorE as integer … → API: MkErrorE_ToInt

(static) MK_STRN MkErrorE_ToString(enum MkErrorE value)

top return the MkErrorE as string … → API: MkErrorE_ToString

enum MkTimeoutE

top Predefined Timeout values … → API: MkTimeoutE

The MkTimeoutE is used wherever a "timeout" is required. As a special feature, in addition to the defined values in 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) enum MkErrorE MkTimeoutE_FromInt(MK_I32 const value, enum MkTimeoutE *value_out)

top return the MkTimeoutE from integer … → API: MkTimeoutE_FromInt

(static) MK_I32 MkTimeoutE_ToInt(enum MkTimeoutE value)

top return the MkTimeoutE as integer … → API: MkTimeoutE_ToInt

(static) MK_STRN MkTimeoutE_ToString(enum MkTimeoutE value)

top return the MkTimeoutE as string … → API: MkTimeoutE_ToString

enum MkTypeE

top basic data-types supported by Programming-Language-Micro-Kernel (PLMK) … → API: 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) enum MkErrorE MkTypeE_FromInt(MK_I32 const value, enum MkTypeE *value_out)

top return the MkTypeE from integer … → API: MkTypeE_FromInt

(static) MK_I32 MkTypeE_ToInt(enum MkTypeE value)

top return the MkTypeE as integer … → API: MkTypeE_ToInt

(static) MK_STRN MkTypeE_ToString(enum MkTypeE value)

top return the MkTypeE as string … → API: MkTypeE_ToString

MkKernel BINARY

C-API: MkKernel_Binary_C_API - MkKernel PACKAGE - operate on a binary al struct of pointer and size …

Attention

In general MkBinaryR is owned by the called function, to get your own copy use MkBinaryDup.

(static,hide) MkBinaryR MkBinaryCreate(MK_SIZE size, MK_BINN data)

top create a binary from data and size ... → API: MkBinaryCreate

(static,hide) MkBinaryR MkBinaryCreateSlice(MkBinaryR const bin, MK_SIZE start, MK_SIZE wide)

top create a binary slice ... → API: MkBinaryCreateSlice

(static,hide) MK_BINN MkBinaryDataGet(MkBinaryR const bin)

top get data pointer from the binary ... → API: MkBinaryDataGet

(static,hide) MkBinaryR MkBinaryDup(MkBinaryR const bin)

top create a binary as duplicate from an already existsing MkBinaryR ... → API: MkBinaryDup

(static,hide) MK_BOOL MkBinaryIsNull(MkBinaryR const bin)

top check if binary is NULL ... → API: MkBinaryIsNull

(static,hide) void MkBinaryLog(MkBinaryR const bin)

top log the binary ... → API: MkBinaryLog

(static,hide) MK_SIZE MkBinarySizeGet(MkBinaryR const bin)

top get size from the binary ... → API: MkBinarySizeGet

MkKernel STRING

C-API: MkKernel_String_C_API - MkKernel PACKAGE - operate on a string as struct of pointer and size …

Attention

In general MkStringR is owned by the called function, to get your own copy use MkStringDup.

(static,hide) MkStringR MkStringCreate(MK_NUM len, MK_STRN str)

top create a str from ptr and len ... → API: MkStringCreate

(static,hide) MkStringR MkStringCreate_1(MK_STRN str)

top create a str from ptr use MK_NULL as end-of-string ... → API: MkStringCreate_1

(static,hide) MK_STRN MkStringDataGet(MkStringR const str)

top get ptr pointer from the string ... → API: MkStringDataGet

(static,hide) MkStringR MkStringDup(MkStringR const str)

top create a string as duplicate from an already existsing MkBinaryR ... → API: MkStringDup

(static,hide) MK_BOOL MkStringIsNULL(MkStringR const strR)

top check if strR is MK_NULL_STR return true or false … → API: MkStringIsNULL

See also

MK_NULL

Parameters

[in]

strR

the string reference to test.

Returns

the a boolean value → true if strR is a MK_NULL_STR.

(static,hide) void MkStringLogI(MkStringR const str, MK_STRN func)

top log the string ... → API: MkStringLogI

(static,hide) MK_NUM MkStringSizeGet(MkStringR const str)

top get len from the string ... → API: MkStringSizeGet

(static,hide) MkStringR MkStringSlice(MkStringR strR, MK_NUM start, MK_NUM len)

top create a slice of strR start at start with max len bytes … → API: MkStringSlice

Parameters

[in]	strR	the string reference to operate on
[in]	start	the start-index, will be strR.ptr + start
[in]	len	the size of the new slize, <0 will be to end of string

Returns

The new MkStringR

• if start > len the MK_NULL -> MkStringR is returned
• if start + len > MkStringR::len the len is truncated

(static,hide) void MkStringSplit(MkStringR strR, MK_NUM *len_out, MK_STRN *str_out)

top split a str into ptr and len … → API: MkStringSplit

---

MkObjectC

MkObjectC CLASS
		Define	MkObjectC - low level definition, access and cast …
		Export	MkObjectC - Export class functions …
		Introspection	MkObjectC - Introspection class functions …
		Misc	MkObjectC - Misc class functions …
MkObjectC TOR
		ObjCreate	call the Constructor from the object
		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 libmkkernel-Instance.
		ObjDup	call the Dup-Constructor from the object
		ObjDup2	call the Dup2-Constructor from the object
		ObjMerge	Constructor - create a new object as a merge from an existing object
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 the entire 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 OBJ
		RefCidN	return the reference-count-recursion-level
		RefDecr	decrement the reference-count
		RefIncr	increment the reference-count
		SelfCreate	create the MkObjectS::self value
		SelfDelete	delete the MkObjectS::self value
		SelfDeleteForce	force delete an instance, last step in instance-destructor
		SelfUnlink	Run the MkTypeS::selfUnlink slot from the instance...
		ObjCopy	call the copy from the object
		ObjReset	free the internal memory of an object and initialize the local variables to default values
		RefDecrWithoutSelf	ATOMIC operation -> unlink self with reference-count.
		RefIncrSelf	ATOMIC operation -> link self with reference-count.
		RefIsLocked	check if object is locked
		RefLock	lock the object
		SelfGet	get the MkObjectS::self value
		SelfNew	return the self pointer for a given obj …
		SelfSet	set the MkObjectS::self value
MkObjectC MISC
		ErrorCatch	convert a programming-language-error into an libmkkernel error …
		HandleGetOfType	Export-Slot - returns typeHdl of the obj .
		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 …

libmkkernel is also called as Programming-Language-Micro-Kernel (PLMK). libmkkernel 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 libmkkernel 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 DEFINE

		Obj	cast a unknown-object into an MkObjectS pointer or NULL if not possible
		ObjCheck	check MkObjectS -> MkObjectS::signature …
		ObjCheckO	check MkObjectS -> MkObjectS::signature …
		ObjN	(const) cast a unknown-object into an MkObjectS pointer or NULL if not possible

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 …
		HandleGet	Handle-Get-Slot - returns a export-hdl to the MkObjectC useable for external storage

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 DEFINE

C-API: MkObjectC_Class_Define_C_API - MkObjectC - low level definition, access and cast …

(static,hide) MK_OBJ MkObj(MK_MNG mng)

top cast a unknown-object into an MkObjectS pointer or NULL if not possible → API: MkObj

(static,hide) MK_BOOL MkObjCheck(MK_MNGN mng)

top check MkObjectS -> MkObjectS::signature … → API: MkObjCheck

Returns

TRUE on valid obj and FALSE an invalid obj

(static,hide) MK_BOOL MkObjCheckO(MK_OBJN obj)

top check MkObjectS -> MkObjectS::signature … → API: MkObjCheckO

Returns

TRUE on valid obj and FALSE an invalid obj

(static,hide) MK_OBJN MkObjN(MK_MNGN mng)

top (const) cast a unknown-object into an MkObjectS pointer or NULL if not possible → API: MkObjN

MkObjectC CLASS EXPORT

MkObjectC - Export class functions …

(static,runtime) void MkObjectHandleDeleteByNetHdl(MK_HDL const netHdl)

top Handle-Delete-Slot - delete a netHdl from handle-storage … → API: MkObjectHandleDeleteByNetHdl_RT

(static,runtime) MK_OBJ MkObjectHandleResolve(MK_HDL const netHdl)

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

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

(runtime) void MkObjectHandleDelete(MK_OBJ const netObj)

top Handle-Delete-Slot - delete a netObj from handle-storage … → API: MkObjectHandleDelete_RT

(runtime) MK_HDL MkObjectHandleGet(MK_OBJ const obj)

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

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

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

MkObjectC CLASS INTROSPECTION

MkObjectC - Introspection class functions …

(static,runtime) MK_OBJ MkObjectInstances()

top get head-instance from linked-list of MkObjectS type … → API: MkObjectInstances_RT

The head-instance is the last instance created.

MK_OBJ MkObjectNext(MK_OBJ const obj)

top get next instance from linked-list of MkObjectS type → API: MkObjectNext

MK_OBJ MkObjectPrev(MK_OBJ const obj)

top get previous instance from linked-list of MkObjectS type → API: MkObjectPrev

MkObjectC CLASS MISC

MkObjectC - Misc class functions …

(static) MK_OBJ MkObjectGetNull()

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

MkObjectC TOR

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

(constructor,static,runtime,hide) MK_OBJ MkObjCreate(MK_PTR nat, MK_PTR lnk)

top call the Constructor from the object → API: MkObjCreate_RT

Create a new object using type and an additional nat. This requie a MkTypeS::constructor be available

Attention

the type have to be resolved fist, already done in MkObjCreate->MkTypeResolve

(static,runtime) void MkObjectDeleteCallbackCleanup(MK_STRN ident)

top cleanup the DeleteCallback installed with MkObjectDeleteCallbackSetup … → API: MkObjectDeleteCallbackCleanup_RT

See also

MkObjectDeleteCallbackSetup

(static,runtime) enum MkErrorE MkObjectDeleteCallbackSetup(MK_STRN ident, MkObjectDeleteCallF fCall, MK_CBP callback, MK_STRN filter)

top Create/Delete the instance-delete-callback … → API: MkObjectDeleteCallbackSetup_RT

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 !

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 : callback signature

Read more at: Callback signature

MkObjectDeleteCallbackSetup : callback example

Read more at: Callback example

(destructor,runtime) void MkObjectDelete(MK_OBJ obj)

top Delete-Slot - delete an instance. → API: MkObjectDelete_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

(destructor,runtime) void MkObjectDispose(MK_OBJ obj)

top Dispose-Slot - untie the connection between the Native-C-Instance and the libmkkernel-Instance. → API: MkObjectDispose_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. 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.

(runtime,hide) MK_OBJ MkObjDup(MK_OBJ const srcobj)

top call the Dup-Constructor from the object → API: MkObjDup_RT

This is an Instance-Callback the real Dup function called depend on the MkObjectS::type.

• currently supported: ErrorDup, BufferDup, BufferStreamDup, BufferListDup

The Dup-Constructor create a new object-shell, and copy all the internal data from the srcobj to the newobj. After the Dup-Constructor the srcobj is unchanged.

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

Returns

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

See also

MkObjMerge_RT MkObjReset_RT

(runtime,hide) MK_OBJ MkObjDup2(MK_OBJ const srcmng, MK_STRN const ident)

top call the Dup2-Constructor from the object → API: MkObjDup2_RT

The Dup2-Constructor create a new object-shell, and copy all the internal data from the srcobj to the newobj. An additional ident is used to set e name ressource After the Dup2-Constructor the srcobj is unchanged.

Returns

the new object or MK_NULL if no Dup2-Constructor fails

See also

MkObjMerge MkObjReset MkTypeDup2

(runtime,hide) MK_OBJ MkObjMerge(MK_OBJ const obj)

top Constructor - create a new object as a merge from an existing object → API: MkObjMerge_RT

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 object-reset 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]	obj	The source-object of the merge.

Returns

The new object or MK_NULL if no Merge-Constructor is available

Attention

The new object have to be deleted.

See also

MkObjDup_RT MkObjReset_RT MkObjectDelete

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,runtime) void MkDbgM(MK_STRN const message, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

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

(runtime) enum MkErrorE MkDbgDump(MK_OBJN const obj, MK_STRN const message, MK_STRN const callfunc)

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

Attention

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

(runtime) void MkDbgL(MK_OBJN fmtobj, MK_STRN const message, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

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

The marker is prefixed with object data from th fmtobj.

(runtime) void MkDbgLogC(MK_OBJN const obj, MK_STRN const callfunc)

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

(runtime) void MkDbgO(MK_OBJN const obj, MK_STRN const callfunc)

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

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.

(runtime) void MkDbgSTACK(MK_OBJN const fmtobj, MK_I32 const skip, MK_I32 const num, MK_STRN const callfunc)

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

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)

(runtime) void MkLogC(MK_OBJN fmtobj, MK_STRN const message, MK_DBG const debug, MK_STRN const callfunc)

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

The logging is only done if 'MqDebug >= level' and 'MqIsSilent == MK_NO' 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

(runtime) void MkLogHEX(MK_OBJN fmtobj, MK_STRN const callfunc, MkBinaryR const data)

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

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

(runtime,hide) void MkLogV(MK_OBJN fmtobj, MK_STRN const callfunc, MK_DBG debug, MK_FST const printfmt, ...)

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

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

(runtime,hide) void MkLogVL(MK_OBJN fmtobj, MK_STRN const callfunc, MK_DBG debug, MK_FST const printfmt, va_list var_list)

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

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

(runtime) void MkObjectLog(MK_OBJN const obj, MK_OBJ fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

top Log-Slot - log the entire object to the MkLogFileC (default: stderr) target … → API: MkObjectLog_RT

Todo

log_doku

slot_doku

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

(runtime) void MkObjectLogDetail(MK_OBJN const obj, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

top log the MkObjectS verbose into the MkLogFileC (default: stderr) … → API: MkObjectLogDetail_RT

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 (runtime) void MkObjectLog(MK_OBJN const obj, MK_OBJ fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

(runtime) void MkObjectLogSimple(MK_OBJN const obj, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

top log the MkObjectS into the MkLogFileC (default: stderr) … → API: MkObjectLogSimple_RT

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 OBJ

C-API: MkObjectC_Obj_C_API - MkObjectC - managed-object details

Managed-Object-Technology (MOT) is a class system in C that is designed to integrate automatically into other software, which of course also includes other programming languages.

See also

Managed-Object

(static,runtime,hide) MK_NUM MkRefCidN()

top return the reference-count-recursion-level → API: MkRefCidN_RT

(static,runtime,hide) void MkRefDecr(MK_OBJ obj)

top decrement the reference-count → API: MkRefDecr_RT

• MkObjectS::refCount will be decremented
• if MkObjectS::refCount <= 0 the destructor will be called.
• the object will not be set to NULL use wrapper MkRefDecr_O, MkRefDecr_X or MkRefDecr_M

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

(static,hide) void MkRefIncr(MK_OBJ obj)

top increment the reference-count → API: MkRefIncr

Parameters

[in]

obj

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

(static,runtime,hide) MK_PTR MkSelfCreate(MK_OBJ const obj, MK_PTR const env)

top create the MkObjectS::self value → API: MkSelfCreate_RT

create the self from the object mng using MkTypeS::selfCreate

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]	env	storage for an application specific environment pointer. (java: JNIEnv*)

Returns

the MkObjectS::self value

(static,runtime,hide) MK_BOOL MkSelfDelete(MK_OBJ const obj)

top delete the MkObjectS::self value → API: MkSelfDelete_RT

delete the self from obj using MkTypeS::selfDelete

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

true if self and mq-obj was deleted and false if self is not available or self-delete does not delete the mq-obj

(static,runtime,hide) MK_BOOL MkSelfDeleteForce(MK_OBJ obj)

top force delete an instance, last step in instance-destructor → API: MkSelfDeleteForce_RT

A instance has two parts an PLMK (Programming-Language-Micro-Kernel)-part and a TPL-part, the PLMK (Programming-Language-Micro-Kernel)-part have to be deleted but the deletion of the TPL-part depend on the TPL object-model-philosophy. Some TPL have a HARD-delete some TPL have only a SOFT-delete, read more at MkObjectDelete.

This function will do the following steps:

1. if available -> call MkTypeS::selfDelete if MkTypeS::selfCreate was called first
2. if 1. was not done and MkTypeS::selfUnlink is available -> unlink the TPL-instance from the PLMK (Programming-Language-Micro-Kernel)-instance.
3. if non-local -> set the MkObjectS::signature to MK_NULL_SIGNATURE and free the memory

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

MK_YES if instance is global or was already deleted and MK_NO if local

(static,runtime,hide) void MkSelfUnlink(MK_OBJ obj)

top Run the MkTypeS::selfUnlink slot from the instance... → API: MkSelfUnlink_RT

An instance has an MQ-part and an LNG-part, both are connected by MkObjectS::self and an LNG-specific proprietary connector. This low-level function will separate the MQpart from the LNG-part, leaving TWO independent objects.

The unlink has the following consequence:

1. When accessing the LNG-part, a NOT-INITIALIZED-EXCEPTION is generated
2. The MQ-part can be deleted without deleting the LNG-part
3. Accessing the MQ-part via the LNG-code creates a new LNG-part connected to the MQ-part

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

Attention

this function has only an effect if the MkTypeS::selfUnlink slot is available

(runtime,hide) MK_OBJ MkObjCopy(MK_OBJ const tgtmng, MK_OBJN const srcmng)

top call the copy from the object → API: MkObjCopy_RT

Returns

the new object or MK_NULL if no Merge-Constructor is available

See also

MkObjDup_RT MkObjReset_RT

(runtime,hide) void MkObjReset(MK_OBJ const obj)

top free the internal memory of an object and initialize the local variables to default values → API: MkObjReset_RT

See also

MkObjDup_RT MkObjMerge_RT

(runtime,hide) MK_OBJ MkRefDecrWithoutSelf(MK_OBJ const obj)

top ATOMIC operation -> unlink self with reference-count. → API: MkRefDecrWithoutSelf_RT

First the MkObjectS::self and MkObjectS::env will be set to NULL and than MkRefDecr is called.

This api-function is used to free libmkkernel ressources on an already destroyed Target-Programming-Language (TPL) instance.

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

always return NULL

See also

MkRefIncr MkSelfSet MkRefIncrSelf

(hide) void MkRefIncrSelf(MK_OBJ const obj, MK_PTR const self, MK_PTR const env)

top ATOMIC operation -> link self with reference-count. → API: MkRefIncrSelf

Parameters

[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
[in]	self	this is the self pointer of the object in the programming-language-shell used for libmkkernel pointer.
[in]	env	storage for an application specific environment pointer. (java: JNIEnv*)

See also

MkRefIncr MkSelfSet MkRefDecrWithoutSelf

(hide) MK_BOOL MkRefIsLocked(MK_OBJ const obj)

top check if object is locked → API: MkRefIsLocked

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 boolean value

(hide) MK_I32 MkRefLock(MK_OBJ const obj)

top lock the object → API: MkRefLock

Parameters

[in]

obj

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

(hide) MK_PTR MkSelfGet(MK_OBJ const obj)

top get the MkObjectS::self value → API: MkSelfGet

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 MkObjectS::self value

(runtime,hide) enum MkErrorE MkSelfNew(MK_OBJ obj, MK_PTR *self_out, MK_PTR const env)

top return the self pointer for a given obj … → API: MkSelfNew_RT

This is an important function because every return of a managed-object in a Target-Programming-Language (TPL) will call this function to check if the self is already set. If MK_YES the self is returned and if MK_NO a new self is created.

the following steps are done:

• if obj has a self pointer (MkSelfGet)
  • if refCount > 0 return the self pointer
  • if refCount <= 0 return an error
• if obj NOT has a self pointer... create a self pointer

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
[out]	self_out	the new libmkkernel object as return
[in]	env	storage for an application specific environment pointer. This pointer will be passed to MkTypeS::selfCreate. (example java: JNIEnv*)

Returns

• MK_OK if self_out is new created
• MK_CONTINUE if self_out was from MkOBJ_R(ctx).self
• MK_ERROR on error

(hide) void MkSelfSet(MK_OBJ const obj, MK_PTR const self, MK_PTR const env)

top set the MkObjectS::self value → API: MkSelfSet

Parameters

[in]	obj	the MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
[in]	self	the target-language-self-pointer usually self or this
[in]	env	storage for an application specific environment pointer. (java: JNIEnv*)

MkObjectC MISC

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

(runtime) MK_ERR MkObjectErrorCatch(MK_OBJN const obj, MK_EXP const exception, MK_STRN const callfunc)

top convert a programming-language-error into an libmkkernel error … → API: MkObjectErrorCatch_RT

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

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

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

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

      MQ_CTX const clmqctx = srvctx->cl[clid];
      MqSendSTART_E (clmqctx);
      MqProxyItem_E (mqctx, clmqctx);
      if (MkErrorCheckI(MqSendEND_AND_WAIT(clmqctx, "ECOI", 5))) {
        MqContextErrorCopy (mqctx, clmqctx);
	MqSendI32_E (mqctx, MkErrorGetNum_0E());
	MqSendSTR_E (mqctx, MkErrorGetText_0E());
	MkErrorReset_1X(mqctx);
      }

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

(runtime) enum MkErrorE MkErrorRaise(MK_ERRN const err) (runtime) enum MkErrorE MkErrorReset(MK_ERR const err, MK_STRN const callfunc, MK_I32 const callline, MK_BOOL const force)

MK_I32 MkObjectHandleGetOfType(MK_OBJ const obj)

top Export-Slot - returns typeHdl of the obj . → API: MkObjectHandleGetOfType

A typeHdl identifies the type the obj belongs to. All instances of the same class 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_BOOL MkObjectIsNull(MK_OBJ const obj)

top ckeck if the object is MK_NULL → API: MkObjectIsNull

(runtime) MK_ERR MkObjectToError(MK_OBJ const obj)

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

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 LibMkKernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

(runtime) MK_STRN MkObjectToName(MK_OBJN const obj)

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

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 LibMkKernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

(runtime) MK_STRN MkObjectToNameOfClass(MK_OBJ const obj)

top Class-Slot - returns the C-Class-Name of the obj as string → API: MkObjectToNameOfClass_RT

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

ObjectToNameOfType	returns the name of the libmkkernel type
ObjectToNameOfClass	returns the name of the C class

(runtime) MK_STRN MkObjectToNameOfType(MK_OBJN const obj)

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

The Programming-Language-Micro-Kernel (PLMK) connect the C language with the libmkkernel runtime. Every class-object in C has an conterpart as libmkkernel 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

(runtime) MK_STRN MkObjectToString(MK_OBJN const inst)

top String-Slot - returns the string representation of the inst … → API: MkObjectToString_RT

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 LibMkKernel 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
		Define	MkBufferC - low level definition, access and cast …
		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) …
		CreateTLS_T	create an new MkBufferC object as T)hread L)ocal S)torage…
		CreateTLS_inout_T	Constructs a MkBufferC instance as T)hread L)ocal S)torage OR reuse inout if possible…
		CreateLOCAL_T	create an new MkBufferC object as L)ocal S)torage…
		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 …
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 libmkkernel is working on data… libmkkernel is working on an MkBufferC object or on a list of MkBufferC objects called MkBufferListC.

MkBufferS 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

MkBufferS CTOR / DTOR

command	synonmym
(constructor,static,runtime) MK_BUF MkBufferCreate(MK_NUM const size)	no
(destructor,runtime) void MkBufferDelete(MK_BUF const buf)	no

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

static enum MkErrorE
Ot_BUF2 ( MQ_SERVICE_CALL_ARGS )
{
  MK_BUF buf;
  int i;
  char str[2] = {'\0', '\0'};
  MqSendSTART_E (mqctx);
  for (i=0; i<3; i++) {
    MqReadBUF_E (mqctx, &buf);
    str[0] = MkBufferGetType1(buf);
    MqSendSTR_E (mqctx, str);
    MqSendBUF_E (mqctx, buf);
  }
  return MqSendRETURN(mqctx);
error:
  return MkErrorStack_1X(mqctx);
}

See also

BufferGetType1 BufferGetType2 BufferGetType3

MkBufferC CLASS

NAVI: top, up

MkBufferC CLASS DEFINE

		Buf	cast a unknown-object into an MkBufferS pointer or NULL if not possible
		BufCheck	check MkBufferS -> MkObjectS::signature …
		BufCheckO	check MkBufferS -> MkObjectS::signature …
		BufN	(const) cast a unknown-object into an MkBufferS pointer or NULL if not possible

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 DEFINE

C-API: MkBufferC_Class_Define_C_API - MkBufferC - low level definition, access and cast …

(static,hide) MK_BUF MkBuf(MK_MNG mng)

top cast a unknown-object into an MkBufferS pointer or NULL if not possible → API: MkBuf

(static,hide) MK_BOOL MkBufCheck(MK_MNGN mng)

top check MkBufferS -> MkObjectS::signature … → API: MkBufCheck

Returns

TRUE on valid buf and FALSE an invalid buf

(static,hide) MK_BOOL MkBufCheckO(MK_OBJN obj)

top check MkBufferS -> MkObjectS::signature … → API: MkBufCheckO

Returns

TRUE on valid buf and FALSE an invalid buf

(static,hide) MK_BUFN MkBufN(MK_MNGN mng)

top (const) cast a unknown-object into an MkBufferS pointer or NULL if not possible → API: MkBufN

MkBufferC CLASS EXPORT

MkBufferC - Export class functions …

(static,runtime) MK_BUF MkBufferHandleResolve(MK_HDL const netHdl)

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

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

(runtime) MK_HDL MkBufferHandleGet(MK_BUF const buf)

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

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

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,runtime) MK_BUF MkBufferInstances()

top get head-instance from linked-list of MkBufferS type … → API: MkBufferInstances_RT

The head-instance is the last instance created.

MK_BUF MkBufferNext(MK_BUF const buf)

top get next instance from linked-list of MkBufferS type → API: MkBufferNext

MK_BUF MkBufferPrev(MK_BUF const buf)

top get previous instance from linked-list of MkBufferS type → API: MkBufferPrev

MkBufferC CLASS MISC

MkBufferC - Misc class functions …

(static) MK_BUF MkBufferGetNull()

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

MkBufferC TOR

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

(constructor,static,runtime) MK_BUF MkBufferCreate(MK_NUM const size)

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

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 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,runtime) MK_BUF MkBufferCreateTLS(MK_STRN const tlsName, MK_BOOL const resetB)

top same as BufferCreate but require no cleanup → API: MkBufferCreateTLS_RT

• 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,runtime) MK_BUF MkBufferCreateBUF(MK_BUFN const val)

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

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,runtime) MK_BUF MkBufferCreate64(MK_NUM const size)

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

(constructor,static,runtime) MK_BUF MkBufferCreate256(MK_NUM const size)

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

(constructor,static,runtime) MK_BUF MkBufferCreate1024(MK_NUM const size)

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

(constructor,static,hide,macro) void MkBufferCreateTLS_T(MK_MACRO_TYP cls, MK_MACRO_TYP name, MK_NUM const size)

top create an new MkBufferC object as T)hread L)ocal S)torage… → API: MkBufferCreateTLS_T

The cls argument is: MkBuffer64S 64 bytes, MkBuffer256S = 256 bytes, MkBuffer1024S = 1024 bytes,

Parameters

[in]	cls	A subclass of MkBufferS with predefined ILS storage → MkBuffer64S, MkBuffer256S and MkBuffer1024S
	name	the name of the new MkBufferC
	size	the initial size of the new MkBufferC

Note

This function is intended as a replacement for MkBufferCreateTLS for the C programming language.

#define MkBufferCreateTLS_T(cls,name,size)          \
  static MkThreadLocal cls##R name##R = {0};        \
  MK_BUF name = MkBUF(&name##R);                    \
  if (unlikely(!__MkCheckX(cls,&name##R))) {        \
    MkBufferInit(name,cls##_TT,size);               \
    MkRefIncr_1X(name);                             \
  } else if (MkBUF_R(&name##R).var.cursize) {       \
    MkBufferReset(name);                            \
  }

(constructor,static,hide,macro) void MkBufferCreateTLS_inout_T(MK_MACRO_TYP cls, MK_MACRO_TYP name, MK_BUF inout)

top Constructs a MkBufferC instance as T)hread L)ocal S)torage OR reuse inout if possible… → API: MkBufferCreateTLS_inout_T

Same as MkBufferCreateTLS_T but try to reuse an already existsing inout. If inout is a MK_NULL pointer than a pointer to a local-reference is returned.

#define MkBufferCreateTLS_inout_T(cls,name,inout)                    \
  static MkThreadLocal struct MkBufferS __hidden_##name##R = {0};    \
  MK_BUF name = *inout != NULL ? *inout : &__hidden_##name##R;       \
  if (likely(!__MkCheckX(MkBufferC,name))) {                         \
    MkBufferInit(name,cls##_TT,0);                                   \
    MkRefIncr_1X(name);                                              \
  } else if (name->var.cursize) {                                    \
    MkBufferReset(name);                                             \
  }                                                                  \

(constructor,static,hide,macro) void MkBufferCreateLOCAL_T(MK_MACRO_TYP cls, MK_MACRO_TYP name, MK_NUM const size)

top create an new MkBufferC object as L)ocal S)torage… → API: MkBufferCreateLOCAL_T

The cls argument is: MkBuffer64S 64 bytes, MkBuffer256S = 256 bytes, MkBuffer1024S = 1024 bytes,

hint

access string with bufR.super.buf.storage.first.C

Parameters

[in]	cls	A subclass of MkBufferS with predefined ILS storage → MkBuffer64S, MkBuffer256S and MkBuffer1024S
	name	the name of the new MkBufferC
	size	the initial size of the new MkBufferC

#define MkBufferCreateLOCAL_T(cls,name,size)        \
  cls##R name##R = {0};                             \
  struct MkBufferS * const name = MkBUF(&name##R);  \
  MkBufferInit(name,cls##_TT,size)

(destructor,runtime) void MkBufferDelete(MK_BUF const buf)

top Destructor - delete a MkBufferC instance … → API: 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,runtime) MK_BUF MkBufferDup(MK_BUFN const buf)

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

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,runtime) MK_BUF MkBufferMerge(MK_BUF const buf)

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

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,runtime)) MK_BUF MkBufferCreateTT(MK_TT const val)

top

The BufferCreateTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
(constructor,static,runtime)	MK_BUF	MkBufferCreateI8(MK_I8 const val)	MkBufferCreateI8_RT
(constructor,static,runtime)	MK_BUF	MkBufferCreateI16(MK_I16 const val)	MkBufferCreateI16_RT
(constructor,static,runtime)	MK_BUF	MkBufferCreateI32(MK_I32 const val)	MkBufferCreateI32_RT
(constructor,static,runtime)	MK_BUF	MkBufferCreateI64(MK_I64 const val)	MkBufferCreateI64_RT
(constructor,static,runtime)	MK_BUF	MkBufferCreateSTR(MK_STRN const val)	MkBufferCreateSTR_RT
(constructor,static,runtime)	MK_BUF	MkBufferCreateBIN(MkBinaryR const val)	MkBufferCreateBIN_RT
(constructor,static,runtime)	MK_BUF	MkBufferCreateBOL(MK_BOL const val)	MkBufferCreateBOL_RT
(constructor,static,runtime)	MK_BUF	MkBufferCreateFLT(MK_FLT const val)	MkBufferCreateFLT_RT
(constructor,static,runtime)	MK_BUF	MkBufferCreateDBL(MK_DBL const val)	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 …

(runtime) MK_BUF MkBufferSetBinaryR(MK_BUF const buf, MkBinaryR const val)

top Set the MkBufferC to the val … → API: MkBufferSetBinaryR_RT

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

(runtime) MK_BUF MkBufferSetBUF(MK_BUF const buf, MK_BUFN const val)

top Set the MkBufferC to the val … → API: MkBufferSetBUF_RT

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

(runtime) MK_BUF MkBufferSetStringR(MK_BUF const buf, MkStringR const val)

top Set the MkBufferC to the val … → API: MkBufferSetStringR_RT

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

(runtime,hide) MK_BUF MkBufferSetV(MK_BUF const buf, MK_FST const val, ...)

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

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

(runtime,hide) MK_BUF MkBufferSetVL(MK_BUF const buf, MK_FST const val, va_list var_list)

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

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

((runtime)) MK_BUF MkBufferSetTT(MK_BUF const buf, MK_TT const val)

top

The BufferSetTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
(runtime)	MK_BUF	MkBufferSetI8(MK_BUF const buf, MK_I8 const val)	MkBufferSetI8_RT
(runtime)	MK_BUF	MkBufferSetI16(MK_BUF const buf, MK_I16 const val)	MkBufferSetI16_RT
(runtime)	MK_BUF	MkBufferSetI32(MK_BUF const buf, MK_I32 const val)	MkBufferSetI32_RT
(runtime)	MK_BUF	MkBufferSetI64(MK_BUF const buf, MK_I64 const val)	MkBufferSetI64_RT
(runtime)	MK_BUF	MkBufferSetSTR(MK_BUF const buf, MK_STRN const val)	MkBufferSetSTR_RT
(runtime)	MK_BUF	MkBufferSetBIN(MK_BUF const buf, MkBinaryR const val)	MkBufferSetBIN_RT
(runtime)	MK_BUF	MkBufferSetBOL(MK_BUF const buf, MK_BOL const val)	MkBufferSetBOL_RT
(runtime)	MK_BUF	MkBufferSetFLT(MK_BUF const buf, MK_FLT const val)	MkBufferSetFLT_RT
(runtime)	MK_BUF	MkBufferSetDBL(MK_BUF const buf, MK_DBL const val)	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 …

(runtime) enum MkErrorE MkBufferGetBFL(MK_BUFN const buf, MK_BFL val_inout)

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

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

• If *val_inout is != MK_NULL than the val_inout is populated with the result.
• If *val_inout is MK_NULL than a TLS alocated MkBufferListC is returned owned by 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]	buf	the MkBufferS instance to work on
[out]	val_inout	the pointer to an MkBufferListC object or MULL at error

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Attention

if val_inout is a variable with the value MK_NULL than this function return TLS memory.

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

(runtime) enum MkErrorE MkBufferGetBUF(MK_BUF const buf, MK_BUF *const val_out)

top get a val_out from a MkBufferC … → API: MkBufferGetBUF_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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

(runtime) enum MkErrorE MkBufferGetStringR(MK_BUFN const buf, MkStringR *const val_out)

top get a val_out from a MkBufferC … → API: MkBufferGetStringR_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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 MK_STR is owned by the MkBufferC object -> never free this pointer.

((runtime)) enum MkErrorE MkBufferGetTT(MK_BUFN const buf, MK_TT *const val_out)

top

The BufferGetTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
(runtime)	enum MkErrorE	MkBufferGetI8(MK_BUFN const buf, MK_I8 *const val_out)	MkBufferGetI8_RT
(runtime)	enum MkErrorE	MkBufferGetI16(MK_BUFN const buf, MK_I16 *const val_out)	MkBufferGetI16_RT
(runtime)	enum MkErrorE	MkBufferGetI32(MK_BUFN const buf, MK_I32 *const val_out)	MkBufferGetI32_RT
(runtime)	enum MkErrorE	MkBufferGetI64(MK_BUFN const buf, MK_I64 *const val_out)	MkBufferGetI64_RT
(runtime)	enum MkErrorE	MkBufferGetSTR(MK_BUFN const buf, MK_STRN *const val_out)	MkBufferGetSTR_RT
(runtime)	enum MkErrorE	MkBufferGetBIN(MK_BUFN const buf, MkBinaryR *const val_out)	MkBufferGetBIN_RT
(runtime)	enum MkErrorE	MkBufferGetBOL(MK_BUFN const buf, MK_BOL *const val_out)	MkBufferGetBOL_RT
(runtime)	enum MkErrorE	MkBufferGetFLT(MK_BUFN const buf, MK_FLT *const val_out)	MkBufferGetFLT_RT
(runtime)	enum MkErrorE	MkBufferGetDBL(MK_BUFN const buf, MK_DBL *const val_out)	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).

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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 …

(runtime) MK_BUF MkBufferAppendSTR(MK_BUF const buf, MK_STRN const val)

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

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.c → read and update a MkBufferC

      // START - ReadBUF - Example, read a buffer-object and append a string 
      MK_BUF buf;
      MqReadBUF_E (mqctx,&buf);
      MkBufferAppendSTR(buf,"- a really log text to overwrite the already allocated space");
      MqSendBUF_E (mqctx,buf);
      MqReadI32_E (mqctx,&i);
      MqSendI32_E (mqctx,i+1);
      // END - ReadBUF - Example

(runtime) MK_BUF MkBufferAppendStringR(MK_BUF const buf, MkStringR const val)

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

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.c → read and update a MkBufferC

      // START - ReadBUF - Example, read a buffer-object and append a string 
      MK_BUF buf;
      MqReadBUF_E (mqctx,&buf);
      MkBufferAppendSTR(buf,"- a really log text to overwrite the already allocated space");
      MqSendBUF_E (mqctx,buf);
      MqReadI32_E (mqctx,&i);
      MqSendI32_E (mqctx,i+1);
      // END - ReadBUF - Example

(runtime,hide) MK_I32 MkBufferAppendV(MK_BUF const buf, MK_FST const printfmt, ...)

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

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

(runtime,hide) MK_I32 MkBufferAppendVL(MK_BUF const buf, MK_FST const printfmt, va_list var_list)

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

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

(runtime) MK_NUM MkBufferPop(MK_BUF const buf, MK_STRN const val)

top delete str from the MkBufferC … → API: MkBufferPop_RT

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 MK_STRT

(runtime) MK_NUM MkBufferPush(MK_BUF const buf, MK_STRN const val)

top add str to the MkBufferC … → API: MkBufferPush_RT

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 MK_STRT

MkBufferC INFO

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

(runtime) MK_STRB MkBufferGetType1(MK_BUFN const buf)

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

MK_STRB
MkBufferGetType1_RT (
  MK_RT_ARGS
  MK_BUFN const buf
)
{
  MK_RT_ATTR_HDL_CHECK(buf);
  MK_RT_ATTR_CHECK_RUNTIME_XN(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 '*';
}

(runtime) enum MkTypeE MkBufferGetType2(MK_BUFN const buf)

top return the MkTypeE from a MkBufferC … → API: MkBufferGetType2_RT

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

(runtime) MK_STRN MkBufferGetType3(MK_BUFN const buf)

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

MK_STRN
MkBufferGetType3_RT (
  MK_RT_ARGS
  MK_BUFN const buf
) {
  MK_RT_ATTR_HDL_CHECK(buf);
  MK_RT_ATTR_CHECK_RUNTIME_XN(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 "*";
}

(runtime) MK_BOOL MkBufferIsLocal(MK_BUFN const buf)

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

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

(runtime) void MkBufferLog(MK_BUFN const buf, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

top log the MkBufferC … → API: MkBufferLog_RT

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

(runtime) void MkBufferLogS(MK_BUFN const buf, MK_STRN const varname, MK_OBJN fmtobj, MK_STRN const callfunc)

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

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 …

(runtime) enum MkErrorE MkBufferCastTo(MK_BUF const buf, enum MkTypeE const typ)

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

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime) MK_I32 MkBufferCmp(MK_BUFN const buf1, MK_BUFN const buf2)

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

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.

(runtime) MK_BUF MkBufferCopy(MK_BUF const buf, MK_BUFN const srce)

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

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

(runtime) void MkBufferReset(MK_BUF const buf)

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

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

(runtime) void MkBufferResetFull(MK_BUF const buf)

(runtime) void MkBufferResetFull(MK_BUF const buf)

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

In addition to (runtime) void MkBufferReset(MK_BUF const buf) 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

(runtime) void MkBufferReset(MK_BUF const buf)

(runtime) MK_BUF MkBufferSizeAdd(MK_BUF const buf, MK_NUM const size)

top add size storage to the buf … → API: MkBufferSizeAdd_RT

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

(runtime) MK_BUF MkBufferSizeNew(MK_BUF const buf, MK_NUM const size)

top alloc min size storage to the buf … → API: MkBufferSizeNew_RT

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)

(runtime) MK_BUF MkBufferTemp(MK_BUFN const buf)

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

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 LibMkKernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

(runtime) MK_STRN MkBufferToString(MK_BUFN const inst)

top String-Slot - returns the string representation of the inst … → API: MkBufferToString_RT

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 LibMkKernel 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
		Define	MkBufferStreamC - low level definition, access and cast …
		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) …
		CreateLOCAL_T	Constructs a MkBufferStreamC instance as L)ocal S)torage …
		CreateSTATIC_T	Constructs a MkBufferStreamC instance as S)tatic S)torage …
		CreateTLS	same as BufferStreamCreate but require no cleanup …
		CreateTLS_T	Constructs a MkBufferStreamC instance as T)hread L)ocal S)torage …
		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 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 DEFINE

		Bus	cast a unknown-object into an MkBufferStreamS pointer or NULL if not possible
		BusCheck	check MkBufferStreamS -> MkObjectS::signature …
		BusCheckO	check MkBufferStreamS -> MkObjectS::signature …
		BusN	(const) cast a unknown-object into an MkBufferStreamS pointer or NULL if not possible

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 DEFINE

C-API: MkBufferStreamC_Class_Define_C_API - MkBufferStreamC - low level definition, access and cast …

(static,hide) MK_BUS MkBus(MK_MNG mng)

top cast a unknown-object into an MkBufferStreamS pointer or NULL if not possible → API: MkBus

(static,hide) MK_BOOL MkBusCheck(MK_MNGN mng)

top check MkBufferStreamS -> MkObjectS::signature … → API: MkBusCheck

Returns

TRUE on valid bus and FALSE an invalid bus

(static,hide) MK_BOOL MkBusCheckO(MK_OBJN obj)

top check MkBufferStreamS -> MkObjectS::signature … → API: MkBusCheckO

Returns

TRUE on valid bus and FALSE an invalid bus

(static,hide) MK_BUSN MkBusN(MK_MNGN mng)

top (const) cast a unknown-object into an MkBufferStreamS pointer or NULL if not possible → API: MkBusN

MkBufferStreamC CLASS EXPORT

MkBufferStreamC - Export class functions …

(static,runtime) MK_BUS MkBufferStreamHandleResolve(MK_HDL const netHdl)

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

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

(runtime) MK_HDL MkBufferStreamHandleGet(MK_BUS const bus)

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

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

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,runtime) MK_BUS MkBufferStreamInstances()

top get head-instance from linked-list of MkBufferStreamS type … → API: MkBufferStreamInstances_RT

The head-instance is the last instance created.

MK_BUS MkBufferStreamNext(MK_BUS const bus)

top get next instance from linked-list of MkBufferStreamS type → API: MkBufferStreamNext

MK_BUS MkBufferStreamPrev(MK_BUS const bus)

top get previous instance from linked-list of MkBufferStreamS type → API: MkBufferStreamPrev

MkBufferStreamC CLASS MISC

MkBufferStreamC - Misc class functions …

(static) MK_BUS MkBufferStreamGetNull()

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

MkBufferStreamC TOR

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

(constructor,static,runtime) MK_BUS MkBufferStreamCreate(MK_NUM const size)

top create and initialize an MkBufferStreamC instance … → API: MkBufferStreamCreate_RT

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,runtime) MK_BUS MkBufferStreamCreate64(MK_NUM const size)

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

(constructor,static,runtime) MK_BUS MkBufferStreamCreate256(MK_NUM const size)

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

(constructor,static,runtime) MK_BUS MkBufferStreamCreate1024(MK_NUM const size)

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

(constructor,static,runtime) MK_BUS MkBufferStreamCreate16384(MK_NUM const size)

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

(constructor,static,hide,macro) void MkBufferStreamCreateLOCAL_T(MK_MACRO_TYP cls, MK_MACRO_TYP name, MK_NUM const size)

top Constructs a MkBufferStreamC instance as L)ocal S)torage … → API: MkBufferStreamCreateLOCAL_T

Parameters

[in]	cls	A subclass of MkBufferStreamS with predefined ILS storage → MkBufferStream16384S, MkBufferStream256S, MkBufferStream64S and MkBufferStream1024S
	name	the name of the new MkBufferStreamS instance
	size	the minimum ILS storage to provide, if size exceed the predefined-storage from cls than heap-storage will be use.

See also

MkBufferStreamC_TOR_C_API

#define MkBufferStreamCreateLOCAL_T(cls,name,size)                \
  cls##R name##R = {0};                                           \
  struct MkBufferStreamS * const name = cls##_X2bus(&name##R);    \
  MkBufferStreamInit(name,cls##_TT,size)

(constructor,static,hide,macro) void MkBufferStreamCreateSTATIC_T(MK_MACRO_TYP cls, MK_MACRO_TYP name)

top Constructs a MkBufferStreamC instance as S)tatic S)torage … → API: MkBufferStreamCreateSTATIC_T

Parameters

[in]	cls	A subclass of MkBufferStreamS with predefined ILS storage → MkBufferStream16384S, MkBufferStream256S, MkBufferStream64S and MkBufferStream1024S
	name	the name of the new MkBufferStreamS instance

See also

MkBufferStreamC_TOR_C_API

#define MkBufferStreamCreateSTATIC_T(cls,name)                    \
  static cls##R name##R = {0};                                    \
  struct MkBufferStreamS * const name = cls##_X2bus(&name##R);    \
  if (__MkCheckX(cls,&name##R)) {                                 \
    MkBufferStreamReset(name);                                    \
  } else {                                                        \
    MkBufferStreamInit(name,cls##TT,0);                           \
  }                                                               \

(static,runtime) MK_BUS MkBufferStreamCreateTLS(MK_STRN const tlsName, MK_BOOL const resetB)

top same as BufferStreamCreate but require no cleanup … → API: MkBufferStreamCreateTLS_RT

• 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.c → performance test with TLS storage

static enum MkErrorE
Ot_BUST ( MQ_SERVICE_CALL_ARGS )
{
  MK_BUS bus = MkBufferStreamCreateTLS_1( "perfserver-BUST" );

  while (MqReadItemExists(mqctx)) {
    MkBufferStreamWriteBUF(bus,MqReadBUF_e(mqctx));
  }

  MkBufferStreamPosToStart(bus);

  MqSendSTART_E (mqctx);
  while (MkBufferStreamReadItemExists(bus)) {
    MqSendBUF_E (mqctx, MkBufferStreamReadBUF_e (bus));
  }

error:
  return MqSendRETURN (mqctx);
}

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

(constructor,static,hide,macro) void MkBufferStreamCreateTLS_T(MK_MACRO_TYP cls, MK_MACRO_TYP name)

top Constructs a MkBufferStreamC instance as T)hread L)ocal S)torage … → API: MkBufferStreamCreateTLS_T

Parameters

[in]	cls	A subclass of MkBufferStreamS with predefined ILS storage → MkBufferStream16384S, MkBufferStream256S, MkBufferStream64S and MkBufferStream1024S
	name	the name of the new MkBufferStreamS instance

See also

MkBufferStreamC_TOR_C_API

#define MkBufferStreamCreateTLS_T(cls,name)                       \
  static MkThreadLocal cls##R name##R = {0};                      \
  struct MkBufferStreamS * const name = cls##_X2bus(&name##R);    \
  if (__MkCheckX(cls,&name##R)) {                                 \
    MkBufferStreamReset(name);                                    \
  } else {                                                        \
    MkBufferStreamInit(name,cls##_TT,0);                          \
  }                                                               \

(destructor,runtime) void MkBufferStreamDelete(MK_BUS const bus)

top Destructor - delete a MkBufferStreamC instance … → API: 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,runtime) MK_BUS MkBufferStreamDup(MK_BUSN const src)

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

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,runtime) MK_BUS MkBufferStreamMerge(MK_BUS const bus)

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

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.

(runtime) enum MkErrorE MkBufferStreamReadALL(MK_BUS const bus, MK_BFL const val_inout)

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

If the val_inout is NULL than a temporary MkBufferListC is returned. If the val_inout is not NULL than the memory of the val_inout is reused.

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 MkBufferListC - the storage of the input is reused

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

See also

BufferStreamReadBFL

Attention

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

(runtime) enum MkErrorE MkBufferStreamReadBFL(MK_BUS const bus, MK_BFL *const val_out)

top read a MkBufferListC from the MkBufferStreamC … → API: MkBufferStreamReadBFL_RT

The MkBufferListC represent a list-item-type (MK_LSTT from the MkBufferStreamC. A list-item-type is created with (runtime) enum MkErrorE MkBufferStreamWriteL_START(MK_BUS const bus) and (runtime) enum MkErrorE MkBufferStreamWriteL_END(MK_BUS const bus) 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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

See also

BufferStreamReadALL BufferStreamWriteBFL

Attention

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

(runtime) enum MkErrorE MkBufferStreamReadBUF(MK_BUS const bus, MK_BUF *const val_out)

top read a val_out from the MkBufferStreamC … → API: MkBufferStreamReadBUF_RT

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 (runtime) void MkBufferStreamPosToStart(MK_BUS const bus).

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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

(runtime) enum MkTypeE MkBufferStreamReadGetNextType(MK_BUSN const bus)

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

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

(runtime) MK_NUM MkBufferStreamReadGetNumItems(MK_BUSN const bus)

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

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

(runtime) MK_BOOL MkBufferStreamReadItemExists(MK_BUSN const bus)

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

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, MK_YES or MK_NO

(runtime) enum MkErrorE MkBufferStreamReadL_END(MK_BUS const bus)

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

(runtime) enum MkErrorE MkBufferStreamReadL_START(MK_BUS const bus, MK_BUF buf)

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

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.

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime) enum MkErrorE MkBufferStreamReadLONG(MK_BUS const bus, MK_LONG *const val_out)

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

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Attention

this api-function is NOT portable

See also

(runtime) enum MkErrorE MkBufferStreamWriteLONG(MK_BUS const bus, MK_LONG const val)

(runtime) enum MkErrorE MkBufferStreamReadUndo(MK_BUS const bus)

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

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

((runtime)) enum MkErrorE MkBufferStreamReadTT(MK_BUS const bus, MK_TT *const val_out)

top

The BufferStreamReadTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
(runtime)	enum MkErrorE	MkBufferStreamReadI8(MK_BUS const bus, MK_I8 *const val_out)	MkBufferStreamReadI8_RT
(runtime)	enum MkErrorE	MkBufferStreamReadI32(MK_BUS const bus, MK_I32 *const val_out)	MkBufferStreamReadI32_RT
(runtime)	enum MkErrorE	MkBufferStreamReadI64(MK_BUS const bus, MK_I64 *const val_out)	MkBufferStreamReadI64_RT
(runtime)	enum MkErrorE	MkBufferStreamReadSTR(MK_BUS const bus, MK_STRN *const val_out)	MkBufferStreamReadSTR_RT
(runtime)	enum MkErrorE	MkBufferStreamReadBIN(MK_BUS const bus, MkBinaryR *const val_out)	MkBufferStreamReadBIN_RT
(runtime)	enum MkErrorE	MkBufferStreamReadBOL(MK_BUS const bus, MK_BOL *const val_out)	MkBufferStreamReadBOL_RT
(runtime)	enum MkErrorE	MkBufferStreamReadFLT(MK_BUS const bus, MK_FLT *const val_out)	MkBufferStreamReadFLT_RT
(runtime)	enum MkErrorE	MkBufferStreamReadDBL(MK_BUS const bus, MK_DBL *const val_out)	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 (runtime) void MkBufferStreamPosToStart(MK_BUS const bus).

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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.

(runtime) enum MkErrorE MkBufferStreamWriteBFL(MK_BUS const bus, MK_BFLN const bfl)

top write a MkBufferListC into the MkBufferStreamC … → API: MkBufferStreamWriteBFL_RT

The MkBufferListC represent a list-item-type (MK_LSTT from the MkBufferStreamC. A list-item-type is created with (runtime) enum MkErrorE MkBufferStreamWriteL_START(MK_BUS const bus) and (runtime) enum MkErrorE MkBufferStreamWriteL_END(MK_BUS const bus) 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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

See also

BufferStreamWriteL_FLAT BufferStreamReadBFL

(runtime) enum MkErrorE MkBufferStreamWriteBUF(MK_BUS const bus, MK_BUFN const val)

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

After every write the current-access-position is incremented by one, use (runtime) void MkBufferStreamReset(MK_BUS const bus) 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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime) enum MkErrorE MkBufferStreamWriteBUS_FLAT(MK_BUS const bus, MK_BUSN const add)

top write a MkBufferStreamC into the MkBufferStreamC … → API: MkBufferStreamWriteBUS_FLAT_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime) enum MkErrorE MkBufferStreamWriteHDL(MK_BUS const bus, MK_I32 const val)

top write the handle into the MkBufferStreamC … → API: MkBufferStreamWriteHDL_RT

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.

(runtime) enum MkErrorE MkBufferStreamWriteL_END(MK_BUS const bus)

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

(runtime) enum MkErrorE MkBufferStreamWriteL_FLAT(MK_BUS const bus, MK_BFL const bfl)

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

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

See also

MkBufferStreamReadBFL

(runtime) enum MkErrorE MkBufferStreamWriteL_START(MK_BUS const bus)

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

(runtime) enum MkErrorE MkBufferStreamWriteLONG(MK_BUS const bus, MK_LONG const val)

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

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Attention

this api-function is NOT portable

See also

(runtime) enum MkErrorE MkBufferStreamReadLONG(MK_BUS const bus, MK_LONG *const val_out)

(runtime,hide) enum MkErrorE MkBufferStreamWriteV(MK_BUS const bus, MK_STRN const fmt, ...)

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

(runtime,hide) enum MkErrorE MkBufferStreamWriteVL(MK_BUS const bus, MK_STRN const fmt, va_list ap)

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

((runtime)) enum MkErrorE MkBufferStreamWriteTT(MK_BUS const bus, MK_TT const val)

top

The BufferStreamWriteTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
(runtime)	enum MkErrorE	MkBufferStreamWriteI8(MK_BUS const bus, MK_I8 const val)	MkBufferStreamWriteI8_RT
(runtime)	enum MkErrorE	MkBufferStreamWriteI32(MK_BUS const bus, MK_I32 const val)	MkBufferStreamWriteI32_RT
(runtime)	enum MkErrorE	MkBufferStreamWriteI64(MK_BUS const bus, MK_I64 const val)	MkBufferStreamWriteI64_RT
(runtime)	enum MkErrorE	MkBufferStreamWriteSTR(MK_BUS const bus, MK_STRN const val, MK_NUM const len)	MkBufferStreamWriteSTR_RT
(runtime)	enum MkErrorE	MkBufferStreamWriteBIN(MK_BUS const bus, MkBinaryR const val)	MkBufferStreamWriteBIN_RT
(runtime)	enum MkErrorE	MkBufferStreamWriteBOL(MK_BUS const bus, MK_BOL const val)	MkBufferStreamWriteBOL_RT
(runtime)	enum MkErrorE	MkBufferStreamWriteFLT(MK_BUS const bus, MK_FLT const val)	MkBufferStreamWriteFLT_RT
(runtime)	enum MkErrorE	MkBufferStreamWriteDBL(MK_BUS const bus, MK_DBL const val)	MkBufferStreamWriteDBL_RT

write a PRIMITIVE TYPE into the MkBufferStreamC …

After every write the current-access-position is incremented by one, use (runtime) void MkBufferStreamReset(MK_BUS const bus) 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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

MkBufferStreamC MISC

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

(runtime) MK_BUS MkBufferStreamCopy(MK_BUS const bus, MK_BUSN const src)

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

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

(runtime) void MkBufferStreamLog(MK_BUS const bus, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

top log the MkBufferStreamC … → API: MkBufferStreamLog_RT

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)

(runtime) void MkBufferStreamPosToStart(MK_BUS const bus)

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

(runtime) void MkBufferStreamReset(MK_BUS const bus)

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

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

(runtime) void MkBufferStreamResetFull(MK_BUS const bus)

(runtime) void MkBufferStreamResetFull(MK_BUS const bus)

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

In addition to (runtime) void MkBufferStreamReset(MK_BUS const bus) 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

(runtime) void MkBufferStreamReset(MK_BUS const bus)

(runtime) MK_BFL MkBufferStreamToBFL(MK_BUSN const bus)

top convert the bus into a MkBufferListC … → API: MkBufferStreamToBFL_RT

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 LibMkKernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

(runtime) MK_STRN MkBufferStreamToString(MK_BUSN const inst)

top String-Slot - returns the string representation of the inst … → API: MkBufferStreamToString_RT

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 LibMkKernel 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
		Define	MkBufferListC - low level definition, access and cast …
		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)
		CreateLOCAL_T	create a MkBufferListC instance on local-memory and return an pointer as instance …
		CreateSTATIC_T	create a MkBufferListC instance on static-storage …
		CreateTLS	same as BufferListCreate but require no cleanup …
		CreateTLS_inout_T	create a MkBufferListC instance as thread-local-torage OR reuse inout if possible…
		CreateTLS_T	create a MkBufferListC instance as thread-local-torage …
		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 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 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 …

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.

MkBufferListS 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

MkBufferListS CTOR / DTOR

command	alias
(constructor,static,runtime) MK_BFL MkBufferListCreate(MK_NUM const size)	no
(destructor,runtime) void MkBufferListDelete(MK_BFL bfl)	no

MkBufferListC CLASS

NAVI: top, up

MkBufferListC CLASS DEFINE

		Bfl	cast a unknown-object into an MkBufferListS pointer or NULL if not possible
		BflCheck	check MkBufferListS -> MkObjectS::signature …
		BflCheckO	check MkBufferListS -> MkObjectS::signature …
		BflN	(const) cast a unknown-object into an MkBufferListS pointer or NULL if not possible

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 DEFINE

C-API: MkBufferListC_Class_Define_C_API - MkBufferListC - low level definition, access and cast …

(static,hide) MK_BFL MkBfl(MK_MNG mng)

top cast a unknown-object into an MkBufferListS pointer or NULL if not possible → API: MkBfl

(static,hide) MK_BOOL MkBflCheck(MK_MNGN mng)

top check MkBufferListS -> MkObjectS::signature … → API: MkBflCheck

Returns

TRUE on valid bfl and FALSE an invalid bfl

(static,hide) MK_BOOL MkBflCheckO(MK_OBJN obj)

top check MkBufferListS -> MkObjectS::signature … → API: MkBflCheckO

Returns

TRUE on valid bfl and FALSE an invalid bfl

(static,hide) MK_BFLN MkBflN(MK_MNGN mng)

top (const) cast a unknown-object into an MkBufferListS pointer or NULL if not possible → API: MkBflN

MkBufferListC CLASS EXPORT

MkBufferListC - Export class functions …

(static,runtime) MK_BFL MkBufferListHandleResolve(MK_HDL const netHdl)

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

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

(runtime) MK_HDL MkBufferListHandleGet(MK_BFL const bfl)

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

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

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,runtime) MK_BFL MkBufferListInstances()

top get head-instance from linked-list of MkBufferListS type … → API: MkBufferListInstances_RT

The head-instance is the last instance created.

MK_BFL MkBufferListNext(MK_BFL const bfl)

top get next instance from linked-list of MkBufferListS type → API: MkBufferListNext

MK_BFL MkBufferListPrev(MK_BFL const bfl)

top get previous instance from linked-list of MkBufferListS type → API: MkBufferListPrev

MkBufferListC CLASS MISC

MkBufferListC - Misc class functions …

(static) MK_BFL MkBufferListGetNull()

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

MkBufferListC TOR

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

(constructor,static,runtime) MK_BFL MkBufferListCreate(MK_NUM const size)

top Constructs a MkBufferC instance with size storage… → API: MkBufferListCreate_RT

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,runtime) MK_BFL MkBufferListCreateLA(MK_BAC const args)

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

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

(constructor,static,hide,macro) void MkBufferListCreateLOCAL_T(MK_MACRO_TYP name, MK_NUM const num)

top create a MkBufferListC instance on local-memory and return an pointer as instance … → API: MkBufferListCreateLOCAL_T

Attention

The local-storage must be freed with MkBufferListFree.

Parameters

name	is the instance-pointer and nameR is the instance-reference.
num	is the minimal-size of the initial buffer-list, size will be inflated if necessary.

#define MkBufferListCreateLOCAL_T(name,num)        \
  struct MkBufferListS name##R = {0};              \
  struct MkBufferListS * const name = &name##R;    \
  MkBufferListInit_RT(MK_RT_CALL name, num)

(constructor,static,hide,macro) void MkBufferListCreateSTATIC_T(MK_MACRO_TYP name, MK_NUM const num)

top create a MkBufferListC instance on static-storage … → API: MkBufferListCreateSTATIC_T

Attention

The static-storage must not be freed.
If the storage exceed the predefined-storage (MkBufferListS_bls_size) the memory will switch to heap-memory.
The next call to the same function will reuse the heap-memory. If required the memory can be freed with MkBufferListFree.

Parameters

name	is the instance-pointer and nameR is the instance-reference.
num	is the minimal-size of the initial buffer-list, size will be inflated if necessary.

#define MkBufferListCreateSTATIC_T(name,num)       \
  static struct MkBufferListS name##R = {0};       \
  struct MkBufferListS * const name = &name##R;    \
  if (__MkCheckX(MkBufferListC,&name##R)) {        \
    MkBufferListReset_RT(MK_RT_CALL name);         \
  } else {                                         \
    MkBufferListInit_RT(MK_RT_CALL name,num);      \
  }

(static,runtime) MK_BFL MkBufferListCreateTLS(MK_STRN const tlsName, MK_BOOL const resetB)

top same as BufferListCreate but require no cleanup … → API: MkBufferListCreateTLS_RT

• 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.c → performance test with TLS storage

static enum MkErrorE
Ot_BFLT ( MQ_SERVICE_CALL_ARGS )
{
  MK_BFL bfl = MkBufferListCreateTLS_1( "perfserver-BFLT" );
 
  while (MqReadItemExists(mqctx)) {
    MkBufferListAppendBUF(bfl,MqReadBUF_e(mqctx));
  }
 
  MqSendSTART_E (mqctx);
  for (int i=0; i<bfl->cursize; i++) {
    MqSendBUF_E (mqctx, MkBufferListIndexGet_e (bfl,i));
  }
 
error:
  return MqSendRETURN (mqctx);
}

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,hide,macro) void MkBufferListCreateTLS_inout_T(MK_MACRO_TYP name, MK_NUM const num, MK_BFL inout)

top create a MkBufferListC instance as thread-local-torage OR reuse inout if possible… → API: MkBufferListCreateTLS_inout_T

The inout is an external-storage or MK_NULL - the external storage will be reused or if MK_NULL the internal thread-local-storage is used.

Attention

The thread-local-storage must not be freed.
If the storage exceed the predefined-storage (MkBufferListS_bls_size) the memory will switch to heap-memory.
The next call to the same function will reuse the heap-memory. If required the memory can be freed with MkBufferListFree.

Parameters

name	is the instance-pointer and nameR is the instance-reference.
num	is the minimal-size of the initial buffer-list, size will be inflated if necessary.
inout	is the preferred-storage, if MK_NULL the thread-local-storage is used.

#define MkBufferListCreateTLS_inout_T(name,num,inout)                    \
  static MkThreadLocal struct MkBufferListS __hidden_##name##R = {0};    \
  MK_BFL name = *inout != NULL ? *inout : &__hidden_##name##R;           \
  if (likely(__MkCheckX(MkBufferListC,name))) {                          \
    MkBufferListReserve_RT(MK_RT_CALL name,num);                         \
  } else {                                                               \
    MkBufferListInit_RT(MK_RT_CALL name,num);                            \
    MkRefIncr_1X(name);                                                  \
  }

(constructor,static,hide,macro) void MkBufferListCreateTLS_T(MK_MACRO_TYP name, MK_NUM const num)

top create a MkBufferListC instance as thread-local-torage … → API: MkBufferListCreateTLS_T

Attention

The thread-local-storage must not be freed.
If the storage exceed the predefined-storage (MkBufferListS_bls_size) the memory will switch to heap-memory.
The next call to the same function will reuse the heap-memory. If required the memory can be freed with MkBufferListFree.

Parameters

name	is the instance-pointer and nameR is the instance-reference.
num	is the minimal-size of the initial buffer-list, size will be inflated if necessary.

Attention

on update -> update tmpl/high_lng.h as well !!

#define MkBufferListCreateTLS_T(name,num)                     \
  static MkThreadLocal struct MkBufferListS name##R = {0};    \
  MK_BFL name = &name##R;                                     \
  if (likely(__MkCheckX(MkBufferListC,&name##R))) {           \
    MkBufferListReserve_RT(MK_RT_CALL name,num);              \
  } else {                                                    \
    MkBufferListInit_RT(MK_RT_CALL name,num);                 \
    MkRefIncr_1X(name);                                       \
  }

(constructor,static,runtime,hide) MK_BFL MkBufferListCreateVA(MK_STRN const arg0, ...)

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

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,runtime,hide) MK_BFL MkBufferListCreateVAL(MK_STRN const arg0, va_list var_list)

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

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,runtime,hide) MK_BFL MkBufferListCreateVC(MK_I32 argv_num, MK_STRN *argv)

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

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,runtime) void MkBufferListDelete(MK_BFL bfl)

top Destructor - delete a MkBufferListC instance … → API: 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,runtime) MK_BFL MkBufferListDup(MK_BFLN const bfl)

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

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,runtime) MK_BFL MkBufferListMerge(MK_BFL const bfl)

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

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 …

(runtime) void MkBufferListAppendBUF(MK_BFL const bfl, MK_BUF const val)

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

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.

(runtime) void MkBufferListAppendG(MK_BFL const bfl, MK_LONG const val)

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

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

(runtime) MK_BFL MkBufferListAppendLA(MK_BFL const bfl, MK_BAC const 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: MkBufferListAppendLA_RT

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

(runtime) MK_BFL MkBufferListAppendLP(MK_BFL const bfl, MK_BFL const addBufL, MK_NUM position)

top copy a MkBufferListS list into an MkBufferListS object on position … → API: MkBufferListAppendLP_RT

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

(runtime) void MkBufferListAppendStringR(MK_BFL const bfl, MkStringR const val)

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

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

(runtime) void MkBufferListAppendUP(MK_BFL const bfl, MK_BUF const addBuf, MK_NUM position)

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

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

(runtime,hide) void MkBufferListAppendV(MK_BFL const bfl, MK_FST const printfmt, ...)

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

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

(runtime,hide) MK_BFL MkBufferListAppendVA(MK_BFL const bfl, MK_STRN arg0, ...)

top append a variable number of strings to an MkBufferListS object … → API: MkBufferListAppendVA_RT

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.

(runtime,hide) MK_BFL MkBufferListAppendVAL(MK_BFL const bfl, MK_STRN arg0, va_list var_list)

top append a variable number of strings to an MkBufferListS object … → API: MkBufferListAppendVAL_RT

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.

(runtime,hide) MK_BFL MkBufferListAppendVC(MK_BFL const bfl, MK_I32 argv_num, MK_STRN *argv)

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

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

(runtime,hide) void MkBufferListAppendVL(MK_BFL const bfl, MK_FST const printfmt, va_list var_list)

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

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

((runtime)) void MkBufferListAppendTT(MK_BFL const bfl, MK_TT const val)

top

The BufferListAppendTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
(runtime)	void	MkBufferListAppendI8(MK_BFL const bfl, MK_I8 const val)	MkBufferListAppendI8_RT
(runtime)	void	MkBufferListAppendI16(MK_BFL const bfl, MK_I16 const val)	MkBufferListAppendI16_RT
(runtime)	void	MkBufferListAppendI32(MK_BFL const bfl, MK_I32 const val)	MkBufferListAppendI32_RT
(runtime)	void	MkBufferListAppendI64(MK_BFL const bfl, MK_I64 const val)	MkBufferListAppendI64_RT
(runtime)	void	MkBufferListAppendSTR(MK_BFL const bfl, MK_STRN const val)	MkBufferListAppendSTR_RT
(runtime)	void	MkBufferListAppendBIN(MK_BFL const bfl, MkBinaryR const val)	MkBufferListAppendBIN_RT
(runtime)	void	MkBufferListAppendBOL(MK_BFL const bfl, MK_BOL const val)	MkBufferListAppendBOL_RT
(runtime)	void	MkBufferListAppendFLT(MK_BFL const bfl, MK_FLT const val)	MkBufferListAppendFLT_RT
(runtime)	void	MkBufferListAppendDBL(MK_BFL const bfl, MK_DBL const val)	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.

(runtime) MK_BOOL MkBufferListCheckOption(MK_BFL const bfl, MK_STRN const opt, MK_BOOL const onlyFirst)

top search for boolean option in MkBufferListS list and return MK_BOL value … → API: MkBufferListCheckOption_RT

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

(runtime) enum MkErrorE MkBufferListCheckOptionBUF(MK_BFL const bfl, MK_STRN const opt, MK_BUF const defval, MK_BOOL const onlyFirst, MK_BUF *const val_out)

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

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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 LibMkKernel function and therefore never becomes MK_NULL for a non-error result.
  For details on the out/return value, see: MkKernel_Storage_C_API.

((runtime)) enum MkErrorE MkBufferListCheckOptionTT(MK_BFL const bfl, MK_STRN const opt, MK_TT const defval, MK_BOOL const onlyFirst, MK_TT *const val_out)

top

The BufferListCheckOptionTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
(runtime)	enum MkErrorE	MkBufferListCheckOptionI8(MK_BFL const bfl, MK_STRN const opt, MK_I8 const defval, MK_BOOL const onlyFirst, MK_I8 *const val_out)	MkBufferListCheckOptionI8_RT
(runtime)	enum MkErrorE	MkBufferListCheckOptionI16(MK_BFL const bfl, MK_STRN const opt, MK_I16 const defval, MK_BOOL const onlyFirst, MK_I16 *const val_out)	MkBufferListCheckOptionI16_RT
(runtime)	enum MkErrorE	MkBufferListCheckOptionI32(MK_BFL const bfl, MK_STRN const opt, MK_I32 const defval, MK_BOOL const onlyFirst, MK_I32 *const val_out)	MkBufferListCheckOptionI32_RT
(runtime)	enum MkErrorE	MkBufferListCheckOptionI64(MK_BFL const bfl, MK_STRN const opt, MK_I64 const defval, MK_BOOL const onlyFirst, MK_I64 *const val_out)	MkBufferListCheckOptionI64_RT
(runtime)	enum MkErrorE	MkBufferListCheckOptionSTR(MK_BFL const bfl, MK_STRN const opt, MK_STRN const defval, MK_BOOL const onlyFirst, MK_STRN *const val_out)	MkBufferListCheckOptionSTR_RT
(runtime)	enum MkErrorE	MkBufferListCheckOptionBOL(MK_BFL const bfl, MK_STRN const opt, MK_BOOL const defval, MK_BOOL const onlyFirst, MK_BOOL *const val_out)	MkBufferListCheckOptionBOL_RT
(runtime)	enum MkErrorE	MkBufferListCheckOptionFLT(MK_BFL const bfl, MK_STRN const opt, MK_FLT const defval, MK_BOOL const onlyFirst, MK_FLT *const val_out)	MkBufferListCheckOptionFLT_RT
(runtime)	enum MkErrorE	MkBufferListCheckOptionDBL(MK_BFL const bfl, MK_STRN const opt, MK_DBL const defval, MK_BOOL const onlyFirst, MK_DBL *const val_out)	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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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 …

(runtime) enum MkErrorE MkBufferListIndexDelete(MK_BFL const bfl, MK_NUM const index, MK_NUM const numitems, MK_BOOL const doDelete)

top delete the index'th list item from the MkBufferListS object … → API: MkBufferListIndexDelete_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime) enum MkErrorE MkBufferListIndexGet(MK_BFLN const bfl, MK_NUM const index, MK_BUF *const val_out)

top get (read only) the index object from bfl … → API: MkBufferListIndexGet_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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

(runtime) MK_BUF MkBufferListIndexGetBUF(MK_BFL const bfl, MK_NUM index)

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

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

(runtime) MK_STRN MkBufferListIndexGetSTR(MK_BFL const bfl, MK_NUM const index)

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

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

(runtime) enum MkErrorE MkBufferListIndexSet(MK_BFL const bfl, MK_NUM const index, MK_BUF const buf)

top set the index object from bfl … → API: MkBufferListIndexSet_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Attention

It is an error if index is not available.

See also

BufferListIndexSetBUF

(runtime) void MkBufferListIndexSetBUF(MK_BFL const bfl, MK_NUM const index, MK_BUF const buf)

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

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

(runtime) void MkBufferListIndexSetSTR(MK_BFL const bfl, MK_NUM const index, MK_STRN const str)

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

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

(runtime) enum MkErrorE MkBufferListIndexExtract(MK_BFL const bfl, MK_NUM const index, MK_BUF *const val_out)

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

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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 …

(runtime) void MkBufferListLog(MK_BFLN bfl, MK_OBJN const fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

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

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

(runtime) void MkBufferListLogS(MK_BFLN const bfl, MK_STRN const varname, MK_OBJN fmtobj, MK_STRN const callfunc)

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

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)

(runtime) void MkBufferListLogSS(MK_BFLN const bfl, MK_STRN const varname, MK_OBJN fmtobj, MK_STRN const callfunc)

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

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)

(runtime) void MkBufferListLogSSS(MK_BFLN const bfl, MK_STRN const varname, MK_OBJN fmtobj, MK_STRN const callfunc)

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

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,runtime) MK_BFL MkBufferListFileGlob(MK_STRN const pattern_match)

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

(runtime) void MkBufferListMove(MK_BFL const to, MK_BFL const from)

top move all internal data from from to the end of to … → API: MkBufferListMove_RT

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

(runtime) void MkBufferListCopy(MK_BFL const bfl, MK_BFLN const src)

top copy all internal data from src to tgt … → API: MkBufferListCopy_RT

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

(runtime) MK_BFL MkBufferListPositionMerge(MK_BFL const bfl, MK_BFL const source, MK_NUM position)

top merge a MkBufferListS list into an MkBufferListS object on position … → API: MkBufferListPositionMerge_RT

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

(runtime) MK_I32 MkBufferListCmp(MK_BFLN const bfl, MK_BFLN const bfl2)

top compare two buffer-list … → API: MkBufferListCmp_RT

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

(runtime) void MkBufferListReserve(MK_BFL const bfl, MK_NUM const num)

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

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.

(runtime) MK_BFL MkBufferListReset(MK_BFL bfl)

top reset a MkBufferListC object … → API: MkBufferListReset_RT

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

(runtime) MK_NUM MkBufferListSearchC(MK_BFLN const bfl, MK_STRN const str, MK_NUM const len, MK_NUM const startindex)

top search MK_STR item from a MkBufferListS object starting at startindex … → API: MkBufferListSearchC_RT

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

(runtime) MK_NUM MkBufferListSize(MK_BFLN const bfl)

top get the number-of-items in the bfl … → API: MkBufferListSize_RT

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

(runtime) MK_BFL MkBufferListSort(MK_BFL const bfl)

top sort a MkBufferListC … → API: MkBufferListSort_RT

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

(runtime) MK_BUF MkBufferListToBuffer(MK_BFLN const bfl)

top Export a bfl into an MkBufferC using an MkBufferStreamC … → API: MkBufferListToBuffer_RT

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 LibMkKernel function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

---

MkErrorC

MkErrorC CLASS
		Define	MkErrorC - low level definition, access and cast …
		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 MK_ERROR and do not raise an target-language-exception …
		Raise	convert an libmkkernel error into an programming-language-error and raise afterwards. …
		SetC	'set' and 'raise' the MkErrorC using a string-message and a errnum-number …
		SetE	set the MkErrorC from a MkErrorC copy and raise an error …
		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 MqIEvent 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 …
		PANIC	panic-system-error - panic on next error …
		PRINT	ignore-system-error - print the next error into MkLogFileC …
MkErrorC MISC
		Catch	convert a programming-language-error into an libmkkernel 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 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 …

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 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 libmkkernel into the error-handling-code of the target C.

Example from Filter6.c → use MqContextErrorCatch to convert a C error into a libmkkernel error

int
main (
  const int argc,
  MK_STRN argv[]
)
{
  MqRtSetup_NULL;

  // define the new type
  Filter6TT = MkTypeDup2(MqContextC_TT,"Filter6");
  Filter6TT->objsize = sizeof(struct FilterCtxS);
  Filter6T->fHelp = FilterHelp;

  // create the factory
  MQ_FCT mqfct = MqFactoryAdd(MK_ERROR_PANIC, Filter6Factory, NULL,NULL,NULL,NULL,NULL,NULL,NULL,"Filter6");
  MQ_CTX mqctx = NULL;

#ifdef BUG1
  // for BUG testing in 'trans2-2-T1aE-...'
  MqFactoryInitial(mqfct);
#endif

  // parse the command-line
  MK_BFL args = MkBufferListCreateVC (argc, argv);

  // search for option "--retryCnt"
  MkBufferListCheckOptionI32_E (args, "--retryCnt", 3, true, &retryCnt);

  // create the filter
  MqFactoryNew_E (mqfct, NULL, &mqctx);

  // create the link
  MqLinkCreate_E (mqctx, args);

  // start event-loop and wait forever
  MqProcessEvent_E (mqctx, MQ_WAIT_FOREVER, MK_TIMEOUT_USER);

  // finish and exit
error:
  MkBufferListDelete(args);
  MqExit_1 (mqctx);
}

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 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 MK_YES or MK_NO …

Attention

This is just a placeholder and have to be implemented in the Target-Programming-Language (TPL).

Example: test case to check KILL and RECOVER feature, check on MkExceptionC

    MK_BUF VAL = MqReadBUF_e(mqctx);
    clmqctx = MqContextCreate (ClientTT, NULL);
    MqConfigSetPrefix(clmqctx,"cl");
    MqConfigSetPostfix(clmqctx,"-1");
    MkErrorCheck (ClientCreateParent2( MK_RT_CALL mqctx, clmqctx));
    MK_I32 PID=0;
    MqSend_E(clmqctx, "W", "GPID@I", &PID);
    MkSysKill_E(MkOBJ(mqctx),PID,9);
    MK_I32 RET=0;
    for (int i=1; i<=3; i++) {
      if (MkErrorCheckI(MqSend(clmqctx, "W", "ECOI:U@I", VAL, &RET))) {
        if (MkErrorIsSOCKET_0E()) {
          MkErrorReset_1X(clmqctx);
          MqLinkConnect(clmqctx);
          continue;
        } else {
          goto error;
        }
      }
      break;
    }
    MqSendSTART_E(mqctx);
    MqSendI32_E (mqctx, RET);

Returns

the result of the check, MK_YES or MK_NO

Parameters

[in]

exception

the exception object from C, if MK_NULL the global exception object is used

MkErrorC CLASS

NAVI: top, up

MkErrorC CLASS DEFINE

		Err	cast a unknown-object into an MkErrorS pointer or NULL if not possible
		ErrCheck	check MkErrorS -> MkObjectS::signature …
		ErrCheckO	check MkErrorS -> MkObjectS::signature …
		ErrN	(const) cast a unknown-object into an MkErrorS pointer or NULL if not possible

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 DEFINE

C-API: MkErrorC_Class_Define_C_API - MkErrorC - low level definition, access and cast …

(static,hide) MK_ERR MkErr(MK_MNG mng)

top cast a unknown-object into an MkErrorS pointer or NULL if not possible → API: MkErr

(static,hide) MK_BOOL MkErrCheck(MK_MNGN mng)

top check MkErrorS -> MkObjectS::signature … → API: MkErrCheck

Returns

TRUE on valid err and FALSE an invalid err

(static,hide) MK_BOOL MkErrCheckO(MK_OBJN obj)

top check MkErrorS -> MkObjectS::signature … → API: MkErrCheckO

Returns

TRUE on valid err and FALSE an invalid err

(static,hide) MK_ERRN MkErrN(MK_MNGN mng)

top (const) cast a unknown-object into an MkErrorS pointer or NULL if not possible → API: MkErrN

MkErrorC CLASS EXPORT

MkErrorC - Export class functions …

(static,runtime) MK_ERR MkErrorHandleResolve(MK_HDL const netHdl)

top Handle-Resolve-Slot - return a MkErrorC from netHdl or MK_NULL if invalid… → API: MkErrorHandleResolve_RT

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

(runtime) MK_HDL MkErrorHandleGet(MK_ERR const err)

top Handle-Get-Slot - returns a export-hdl to the MkErrorC useable for external storage → API: MkErrorHandleGet_RT

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

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,runtime) MK_ERR MkErrorInstances()

top get head-instance from linked-list of MkErrorS type … → API: MkErrorInstances_RT

The head-instance is the last instance created.

MK_ERR MkErrorNext(MK_ERR const err)

top get next instance from linked-list of MkErrorS type → API: MkErrorNext

MK_ERR MkErrorPrev(MK_ERR const err)

top get previous instance from linked-list of MkErrorS type → API: MkErrorPrev

MkErrorC CLASS MISC

MkErrorC - Misc class functions …

(static) MK_ERR MkErrorGetNull()

top Null-Slot - return a MkErrorC typed NULL instance … → API: MkErrorGetNull

MkErrorC TOR

C-API: MkErrorC_TOR_C_API - MkErrorC - various functions to 'create' and 'delete' a MkErrorS …

(destructor,runtime) void MkErrorDelete(MK_ERR err)

top Destructor - delete a MkErrorS object … → API: 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,runtime) MK_ERR MkErrorDup(MK_ERRN const srce)

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

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 …

enum MkErrorE MkErrorGetCode(MK_ERRN const err)

top get the value of MkErrorS::code … → API: MkErrorGetCode

MK_I32 MkErrorGetNum(MK_ERRN const err)

top get the MkErrorS::num. The number can be used as exit-code … → API: MkErrorGetNum

MK_SIZE MkErrorGetSize(MK_ERRN const err)

top get the error-message-size from the exception-object … → API: MkErrorGetSize

MK_STRN MkErrorGetText(MK_ERRN const err)

top get the MkErrorS::text … → API: MkErrorGetText

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

(static,runtime) void MkPanicC(MK_OBJN const errobj, MK_STRN const callfunc, MK_I32 const errnum, MK_STRN const message)

top do a panic with string as argument … → API: MkPanicC_RT

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errobj	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,runtime,hide) void MkPanicV(MK_OBJN const errobj, MK_STRN const callfunc, MK_I32 const errnum, MK_FST const printfmt, ...)

top do a panic with a vararg as argument … → API: MkPanicV_RT

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errobj	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,runtime,hide) void MkPanicVL(MK_OBJN const errobj, MK_STRN const callfunc, MK_I32 const errnum, MK_FST const printfmt, va_list var_list)

top do a panic with a vararg-list as argument … → API: MkPanicVL_RT

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errobj	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

(runtime) void MkErrorAppendC(MK_ERR const err, MK_STRN const message)

top append the message to the MkErrorS::text … → API: MkErrorAppendC_RT

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)

(runtime,hide) void MkErrorAppendV(MK_ERR const err, MK_FST const printfmt, ...)

top append a vararg string to the MkErrorC … → API: MkErrorAppendV_RT

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

(runtime,hide) void MkErrorAppendVL(MK_ERR const err, MK_FST const printfmt, va_list var_list)

top append a va_list string to the MkErrorC … → API: MkErrorAppendVL_RT

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

(runtime) MK_ERR MkErrorNoRaise(MK_ERR const err)

top ignore the next return of MK_ERROR and do not raise an target-language-exception … → API: MkErrorNoRaise_RT

Many functions from the MkErrorXXX return an MkErrorE to signal that an 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 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.c → create and send an background-error message

static enum MkErrorE
BgError ( MQ_SERVICE_CALL_ARGS )
{
  MQ_CTX master = MqSlaveGetMaster(mqctx);
  if (master) {
    MK_ERR err = MkErrorNoRaise(MkErrorFORMAT_1M(master));
    // MkErrorGetTextI and MkErrorSetC using the !! SAME !! memory
    // → need a temporary buffer "ctxbuf.buf"
    MkBufferSetSTR(MkBUF(&master->ctxbuf), MkErrorGetText(err));
    MkErrorSetC(err, MkBUF_R(&master->ctxbuf).storage.first.C, "BGERROR", MkErrorGetNum(err));
    MqSendERROR (master);
  }
  return MkErrorStack_1M_Check(mqctx);
}

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

(runtime) enum MkErrorE MkErrorRaise(MK_ERRN const err)

top convert an libmkkernel error into an programming-language-error and raise afterwards. … → API: MkErrorRaise_RT

If ther is no libmkkernel-error (MkErrorS::code "= #MK_ERROR) than nothing happen. @param [in] err the \ref MkErrorS "MkErrorS" instance to work on - the \e default-error is automatically created on startup. (NULL allowed) \sa \ref doc_mk_c_ErrorCatch "ErrorCatch" \ref doc_mk_c_ErrorReset "ErrorReset"

(runtime) enum MkErrorE MkErrorSetC(MK_ERR err, MK_STRN const message, MK_STRN const callfunc, MK_I32 const errnum)

top 'set' and 'raise' the MkErrorC using a string-message and a errnum-number … → API: MkErrorSetC_RT

The message will be formatted into a libmkkernel 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.

(runtime,hide) enum MkErrorE MkErrorSetE(MK_ERR const err, MK_ERR const newerr)

top set the MkErrorC from a MkErrorC copy and raise an error … → API: MkErrorSetE_RT

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]	newerr	the MkErrorC to be the new default-error

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Attention

Use ErrorNoRaise to avoid raise an error.

(runtime,hide) enum MkErrorE MkErrorSetV(MK_ERR err, MK_STRN const callfunc, MK_I32 const errnum, MK_FST const printfmt, ...)

top set the MkErrorS object using a format string argument list and raise an error … → API: MkErrorSetV_RT

The string argument list will be formatted into a libmkkernel 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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Attention

Use ErrorNoRaise to avoid raise an error.

(runtime,hide) enum MkErrorE MkErrorSetVL(MK_ERR err, MK_STRN const callfunc, MK_I32 const errnum, MK_FST const printfmt, va_list var_list)

top 'set' and 'raise' the MkErrorC using a vararg-list message … → API: MkErrorSetVL_RT

The var_list will be formatted into a libmkkernel 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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

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 MkErrorIsABORT(MK_ERRN const err)

top check on ABORT signal … → API: MkErrorIsABORT

MK_BOOL MkErrorIsEXIT(MK_ERR const err)

top check on APPLICATION-EXIT error … → API: MkErrorIsEXIT

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/c/Filter4.c 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 MkErrorIsSOCKET(MK_ERRN const err)

top check on SOCKET-DOWN error … → API: MkErrorIsSOCKET

MK_BOOL MkErrorIsTIMEOUT(MK_ERRN const err)

top check on TIMEOUT error … → API: MkErrorIsTIMEOUT

(runtime) enum MkErrorE MkErrorSetABORT(MK_ERR const err, MK_STRN const detail, MK_STRN const callfunc)

top send the ABORT signal to the calling stack… → API: MkErrorSetABORT_RT

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

(runtime) void MkErrorSetCode(MK_ERR const err, enum MkErrorE code)

top set the MkErrorS::code value … → API: MkErrorSetCode_RT

(runtime) void MkErrorSetCONTINUE(MK_ERR const err)

top signal end of processing in an MqIEvent callback … → API: MkErrorSetCONTINUE_RT

(runtime) enum MkErrorE MkErrorSetEXIT(MK_ERR const err, MK_STRN const callfunc)

top finish the current callback, return to toplevel and MqExit the application … → API: MkErrorSetEXIT_RT

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

(runtime) enum MkErrorE MkErrorSetSOCKET(MK_ERR const err, MK_STRN const detail, MK_STRN const callfunc)

top create SOCKET-DOWN error … → API: MkErrorSetSOCKET_RT

MkErrorC SYSTEM

C-API: MkErrorC_System_C_API - MkErrorC - various functions to raise a 'System' messagen on MkErrorS …

(static,runtime) MK_ERR MkErrorDEFAULT()

top default-system-error - default-error … → API: MkErrorDEFAULT_RT

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) MK_ERR MkErrorFORMAT(MK_OBJN const fmtobj)

top system-error-format - format and return the default-error … → API: MkErrorFORMAT

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,runtime) MK_ERR MkErrorIGNORE()

top ignore-system-error - ignore the next error … → API: MkErrorIGNORE_RT

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,runtime,hide) MK_ERR MkErrorPANIC()

top panic-system-error - panic on next error … → API: MkErrorPANIC_RT

If the panic-system-error is used as the format-obj of an error-message, the text is formated as usual, but the default-error is not set, instead a MkPanicVL is called and the application terminates.

MkErrorPANIC - usage

Set the MkErrorS::format_of_error attribute to PANIC. The next error-message will be formated as usual and than be reported using MkPanicVL. With MkPanicVL the error will be printed to MkLogFileC (default: stderr) and the application will abort.

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

(static,runtime) MK_ERR MkErrorPRINT()

top ignore-system-error - print the next error into MkLogFileC … → API: MkErrorPRINT_RT

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 …

(runtime) MK_ERR MkErrorCatch(MK_ERR const err, MK_EXP const exception, MK_STRN const callfunc)

top convert a programming-language-error into an libmkkernel error … → API: MkErrorCatch_RT

Same as MkObjectErrorCatch but skip the Error-Prefix in final Target-Programming-Language (TPL).

Example from Bug3.c → catch an error using (runtime) MK_ERR MkErrorCatch(MK_ERR const err, MK_EXP const exception, MK_STRN const callfunc)

  // "C" does not support the "Catch" function because there is ONLY the "LibMqMsgque" error and nothing else.

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

(runtime) void MkErrorLog(MK_ERRN const err, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

top log the error to MkLogFileC (default: stderr) … → API: MkErrorLog_RT

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 (runtime) void MkErrorLog(MK_ERRN const err, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

(runtime) void MkErrorPrintln(MK_ERR const err)

top print the default-error to the MkLogFileC (default: stderr) and clear the error afterwards … → API: MkErrorPrintln_RT

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)

(runtime) enum MkErrorE MkErrorReset(MK_ERR const err, MK_STRN const callfunc, MK_I32 const callline, MK_BOOL const force)

top This function clears the err and resets to MK_OK … → API: MkErrorReset_RT

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

(runtime) enum MkErrorE MkErrorStack(MK_ERR const err, MK_STRN const callfunc, MK_STRN const callfile, MK_I32 const callline)

top check on error and if yes append an ErrorStackFormat to the error-message … → API: MkErrorStack_RT

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)

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime) void MkErrorStackFormat(MK_ERR const err, MK_STRN callfunc, MK_STRN callfile, MK_I32 const callline)

top append an ensemble of func, file and line to the error-message … → API: MkErrorStackFormat_RT

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)

---

MkLogFileC

MkLogFileC CLASS
		Define	MkLogFileC - low level definition, access and cast …
		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 DEFINE

		Lfl	cast a unknown-object into an MkLogFileS pointer or NULL if not possible
		LflCheck	check MkLogFileS -> MkObjectS::signature …
		LflCheckO	check MkLogFileS -> MkObjectS::signature …
		LflN	(const) cast a unknown-object into an MkLogFileS pointer or NULL if not possible

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 DEFINE

C-API: MkLogFileC_Class_Define_C_API - MkLogFileC - low level definition, access and cast …

(static,hide) MK_LFL MkLfl(MK_MNG mng)

top cast a unknown-object into an MkLogFileS pointer or NULL if not possible → API: MkLfl

(static,hide) MK_BOOL MkLflCheck(MK_MNGN mng)

top check MkLogFileS -> MkObjectS::signature … → API: MkLflCheck

Returns

TRUE on valid lfl and FALSE an invalid lfl

(static,hide) MK_BOOL MkLflCheckO(MK_OBJN obj)

top check MkLogFileS -> MkObjectS::signature … → API: MkLflCheckO

Returns

TRUE on valid lfl and FALSE an invalid lfl

(static,hide) MK_LFLN MkLflN(MK_MNGN mng)

top (const) cast a unknown-object into an MkLogFileS pointer or NULL if not possible → API: MkLflN

MkLogFileC CLASS EXPORT

MkLogFileC - Export class functions …

(static,runtime) MK_LFL MkLogFileHandleResolve(MK_HDL const netHdl)

top Handle-Resolve-Slot - return a MkLogFileC from netHdl or MK_NULL if invalid… → API: MkLogFileHandleResolve_RT

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

(runtime) MK_HDL MkLogFileHandleGet(MK_LFL const lfl)

top Handle-Get-Slot - returns a export-hdl to the MkLogFileC useable for external storage → API: MkLogFileHandleGet_RT

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

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,runtime) MK_LFL MkLogFileInstances()

top get head-instance from linked-list of MkLogFileS type … → API: MkLogFileInstances_RT

The head-instance is the last instance created.

MK_LFL MkLogFileNext(MK_LFL const lfl)

top get next instance from linked-list of MkLogFileS type → API: MkLogFileNext

MK_LFL MkLogFilePrev(MK_LFL const lfl)

top get previous instance from linked-list of MkLogFileS type → API: MkLogFilePrev

MkLogFileC CLASS MISC

MkLogFileC - Misc class functions …

(static) MK_LFL MkLogFileGetNull()

top Null-Slot - return a MkLogFileC typed NULL instance … → API: MkLogFileGetNull

MkLogFileC TOR

C-API: MkLogFileC_TOR_C_API - MkLogFileC - various functions to 'create and delete' a MkLogFileS …

(constructor,static,runtime) enum MkErrorE MkLogFileOpen(MK_OBJ errobj, MK_STRN const file, MK_LFL *lfh_out)

top open the log-file in append mode … → API: MkLogFileOpen_RT

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]	errobj	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

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Attention

on error the lfh_out is set to MK_NULL

(destructor,runtime) void MkLogFileClose(MK_LFL lfh)

top Destructor - delete a MkLogFileC instance … → API: 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 …

(runtime) enum MkErrorE MkLogFileGetFile(MK_LFLN lfl, MK_STRN *file_out)

top get the log-file … → API: MkLogFileGetFile_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime) enum MkErrorE MkLogFileWriteC(MK_LFLN lfl, MK_STRN text)

top write to log-file … → API: MkLogFileWriteC_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime,hide) enum MkErrorE MkLogFileWriteV(MK_LFLN lfl, MK_FST printfmt, ...)

top write to log-file … → API: MkLogFileWriteV_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

(runtime,hide) enum MkErrorE MkLogFileWriteVL(MK_LFLN lfl, MK_FST printfmt, va_list var_list)

top write to log-file … → API: MkLogFileWriteVL_RT

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

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

---

MkRuntimeC

MkRuntimeC CLASS
		Define	MkRuntimeC - low level definition, access and cast …
		Export	MkRuntimeC - Export class functions …
		Introspection	MkRuntimeC - Introspection class functions …
		Misc	MkRuntimeC - Misc class functions …
MkRuntimeC CONFIG
		GetDebug	get the MkRuntimeS::debug value …
		GetIsSilent	get the MkRuntimeS::isSilent value …
		GetLogfile	get the MkRuntimeS::logfile value …
		SetCID	CID == context-in-duty.
		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 libmkkernel application environment …

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

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

runtime-separation

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

the runtime provide the following features

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

THREAD ENABLED LIBRARY

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

RUNTIME DEFAULT

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

RUNTIME INTERFACE

‍The goal of the runtime-interface is to provide the best performance for thread and non-thread.

on thread

the cache-access with the MkRuntimeRLS-pointer is used.

• The libmkkernel was build with configure --enable-threads ....
• The application has multiple threads and every PLMK (Programming-Language-Micro-Kernel)-thread has his own MkRuntimeRLS.
• The MkRuntimeRLS itself is created as T)hread-L)ocal-S)torage (TLS).
• The MkRuntimeRLS can be reached via the macro MkRT (slow) or via the MkRuntimeRLS-cache (fast),
• The MkRT is resolving with a tls-resolution-call, using multiple MkRT creates multiple tls-resolution-calls (very slow).
• The runtime-cache is added only once to the function-body and is later reused for every MkRuntimeRLS-access (fast).
• The runtime-cache is added via first-argument (fast) or via a MkRuntimeRLS-object-resolution (also fast, but slower than first-argument) or via MkRT if no first-argument or MkRuntimeRLS-object-resolution is available (slow)
• The MkRuntimeRLS-object-resolution get the MkRuntimeRLS from the MkObjectS::objRt attribute.

on non-thread

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

• The libmkkernel was build with configure --disable-threads ....
• The application has only one therad and only one MkRuntimeRLS.
• The MkRuntimeRLS is created as A)pplication-G)lobal-S)torage (AGS).
• The MkRuntimeRLS can be reached via the macro MkRT, compile-time-resolving with a direct-access (fast)

thread and non-thread

The diffrence between thread and non-thread is hidden behind the MK_RT_*, MkRt* or MkRT* macros.

Characteristics of the runtime:

• The MkRuntimeRLS is defined as: MkThreadLocal struct MkRuntimeS MkRuntimeRLS = {0};.
• The macro MkRT will always resolve to (&MkRuntimeRLS)
• The MkThreadLocal will expand to __thread with thread-support and otherwise to empty.
• There will be exact one MkRuntimeRLS per PLMK (Programming-Language-Micro-Kernel)-thread.
• In a non-threaded-environment only one MkRuntimeRLS exists.
• The new MkRuntimeRLS is initialized with the fist MkRtSetup_xxx call after the thread-creation.

threaded versa non-threaded:

The internal MkRuntimeRLS access is different for thread and non-thread.

‍Always use the MK_RT_xxx and MkRtSetup_xxx macros to get best performane to access the MkRuntimeRLS. Summary: Internal access to the MkRuntimeRLS

threaded	storage	resolve	access	MkRtSetup_xxx	speed
yes	thread-local-storage	run-time	cache	via mkrt	fast enough but slower than non-thread
no	application-global-storage	compile-time	direct	via MkRT	fast

Create the local-cache:

The local-cache is only required for a threaded-environment and is defined internal as mkrt variable initialized with a pointer to the MkRuntimeRLS.

‍do NOT use the mkrt direct because your code will NOT compile in a non-thread environment.

In a runtime-aware function the local-cache is always as first argument in the function.

void myfunc( MK_RT_ARGS arg1, arg2, argX... ) {
  ...
}

In a non-runtime-aware method the local-cache is created using the instance-argument:

void myfunc( instance, arg2, argX... ) {
  MkRtSetup_X(instance)
  ...
}

In a non-runtime-aware static-function the local-cache is created using TLS direct:

void myfunc( instance, arg2, argX... ) {
  MkRtSetup_NULL
  ...
}

In a non-runtime-aware static-function with instance-argument the local-cache is created using instArg:

void myfunc( arg1, instArg, argX... ) {
  MkRtSetup_X(instArg)
  ...
}

Summary: In a non-runtime-aware function use the instance to setup the cache-access otherwise MkRtSetup_NULL:

source	local-cache is created with	example	speed
instance	MkRtSetup_O , MkRtSetup_X	MkRtSetup_X(instance)	fast
runtime	MkRtSetup_NULL	MkRtSetup_NULL	slow in non-static

Access to the runtime:

Do not use mkrt directly because mkrt will disappear in a non-threaded-environment.

access as	macro	threaded	nothreaded	example	speed
reference	MK_RT_REF	(*mkrt)	MkRuntimeRLS	MK_RT_REF.debug	fast if static
pointer	MK_RT_PTR	mkrt	(&MkRuntimeRLS)	MK_RT_PTR->debug	slow

Always try to use the MK_RT_REF for best performance in a threaded and non-threaded-environment.

Define and Call a runtime-aware function:

It is a difference if a runtime-aware function is called with or without argument.

args	function definition	function parser extension	function call
multiple args	MK_RT_ARGS	MK_RT_PARSER	MK_RT_CALL
no args	MK_RT_ARGS_ONLY	MK_RT_PARSER_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 CLASS

NAVI: top, up

MkRuntimeC CLASS DEFINE

		Rt	cast a unknown-object into an MkRuntimeS pointer or NULL if not possible
		RtCheck	check MkRuntimeS -> MkObjectS::signature …
		RtCheckO	check MkRuntimeS -> MkObjectS::signature …
		RtN	(const) cast a unknown-object into an MkRuntimeS pointer or NULL if not possible

MkRuntimeC CLASS EXPORT

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

MkRuntimeC CLASS INTROSPECTION

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

MkRuntimeC CLASS MISC

GetNull

Null-Slot - return a MkRuntimeC typed NULL instance …

MkRuntimeC CLASS DETAILS

C-API: MkRuntimeC_Class_C_API - MkRuntimeC - define the class …

MkRuntimeC CLASS DEFINE

C-API: MkRuntimeC_Class_Define_C_API - MkRuntimeC - low level definition, access and cast …

(static,hide) MK_RT MkRt(MK_MNG mng)

top cast a unknown-object into an MkRuntimeS pointer or NULL if not possible → API: MkRt

(static,hide) MK_BOOL MkRtCheck(MK_MNGN mng)

top check MkRuntimeS -> MkObjectS::signature … → API: MkRtCheck

Returns

TRUE on valid rt and FALSE an invalid rt

(static,hide) MK_BOOL MkRtCheckO(MK_OBJN obj)

top check MkRuntimeS -> MkObjectS::signature … → API: MkRtCheckO

Returns

TRUE on valid rt and FALSE an invalid rt

(static,hide) MK_RTN MkRtN(MK_MNGN mng)

top (const) cast a unknown-object into an MkRuntimeS pointer or NULL if not possible → API: MkRtN

MkRuntimeC CLASS EXPORT

MkRuntimeC - Export class functions …

(static,runtime) MK_RT MkRuntimeHandleResolve(MK_HDL const netHdl)

top Handle-Resolve-Slot - return a MkRuntimeC from netHdl or MK_NULL if invalid… → API: MkRuntimeHandleResolve_RT

The MkRuntimeHandleResolve undo the MkRuntimeHandleGet 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 MkRuntimeHandleGet

Returns

the required handle or MK_NULL if netHdl is invalid

(runtime) MK_HDL MkRuntimeHandleGet(MK_RT const rt)

top Handle-Get-Slot - returns a export-hdl to the MkRuntimeC useable for external storage → API: MkRuntimeHandleGet_RT

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

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]	rt	the MkRuntimeS instance to work on - the mk-runtime argument, used by MK_RT_CALL (C-only)

Returns

the required export-hdl

MkRuntimeC CLASS INTROSPECTION

MkRuntimeC - Introspection class functions …

(static,runtime) MK_RT MkRuntimeInstances()

top get head-instance from linked-list of MkRuntimeS type … → API: MkRuntimeInstances_RT

The head-instance is the last instance created.

MK_RT MkRuntimeNext(MK_RT const rt)

top get next instance from linked-list of MkRuntimeS type → API: MkRuntimeNext

MK_RT MkRuntimePrev(MK_RT const rt)

top get previous instance from linked-list of MkRuntimeS type → API: MkRuntimePrev

MkRuntimeC CLASS MISC

MkRuntimeC - Misc class functions …

(static) MK_RT MkRuntimeGetNull()

top Null-Slot - return a MkRuntimeC typed NULL instance … → API: MkRuntimeGetNull

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 MkRuntimeGetDebug()

top get the MkRuntimeS::debug value … → API: MkRuntimeGetDebug

(static) MK_BOOL MkRuntimeGetIsSilent()

top get the MkRuntimeS::isSilent value … → API: MkRuntimeGetIsSilent

(static) MK_STRN MkRuntimeGetLogfile()

top get the MkRuntimeS::logfile value … → API: MkRuntimeGetLogfile

Attention

the string is owned by libmkkernel -> do not free !!

(static,hide) void MkRuntimeSetCID(MK_OBJ const cid)

top CID == context-in-duty. → API: MkRuntimeSetCID

(static) void MkRuntimeSetDebug(MK_I32 dbg)

top set the MkRuntimeS::debug value … → API: MkRuntimeSetDebug

(static) void MkRuntimeSetIsSilent(MK_BOOL silent)

top set the MkRuntimeS::isSilent value … → API: MkRuntimeSetIsSilent

(static,runtime) enum MkErrorE MkRuntimeSetLogfile(MK_STRN logfile)

top set the MkRuntimeS::logfile value and cleanup old value … → API: MkRuntimeSetLogfile_RT

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 …

(runtime) void MkRuntimeLog(MK_RTN const rt, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)

top log the MkRuntimeC … → API: MkRuntimeLog_RT

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_c_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.c → read a buffer-object and convert single-char-type-identifer to string.

static enum MkErrorE
Ot_BUF2 ( MQ_SERVICE_CALL_ARGS )
{
  MK_BUF buf;
  int i;
  char str[2] = {'\0', '\0'};
  MqSendSTART_E (mqctx);
  for (i=0; i<3; i++) {
    MqReadBUF_E (mqctx, &buf);
    str[0] = MkBufferGetType1(buf);
    MqSendSTR_E (mqctx, str);
    MqSendBUF_E (mqctx, buf);
  }
  return MqSendRETURN(mqctx);
error:
  return MkErrorStack_1X(mqctx);
}

---

SEE ALSO

libmkkernel, ccmkkernel, csmkkernel, javamkkernel, gomkkernel, pymkkernel, rbmkkernel, tclmkkernel, perlmkkernel, phpmkkernel

KEYWORDS

C, unix, socket, message, msgque