ccmkkernel 9.0
Loading...
Searching...
No Matches
ccmkkernel

The Programming-Language-Micro-Kernel Project.

SYNOPSIS

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

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

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

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

To access all features without ccmkkernel prefix use:

include LibMkKernel_cc.h
using namespace ccmkkernel;

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

‍LDADD = path/to/libccmkkernel.la

or

‍mylib_la_LIBADD = path/to/libccmkkernel.la

Example from example/cc/Makefile.am using libccmqmsgque.la (also load libccmkkernel.la and others
noinst_PROGRAMS += ConfigServer
ConfigServer_SOURCES = ConfigServer.cc
ConfigServer_CPPFLAGS = $(libmqmsgque_addon_CPPFLAGS) $(liblcconfig_addon_CPPFLAGS) -I$(theKernel_SRCDIR)/ccmsgque -I$(theLink_SRCDIR)/ccmsgque -I$(theConfig_SRCDIR)/ccmsgque
ConfigServer_CXXFLAGS = $(libmqmsgque_CXXFLAGS) -DMETA_IGNORE_EXTERN
ConfigServer_LDADD = $(theLink_BUILDDIR)/ccmsgque/libccmqmsgque.la $(theConfig_BUILDDIR)/ccmsgque/libcclcconfig.la
if ENABLE_STATIC
ConfigServer_LDFLAGS = $(UBSAN) -static -no-undefined
ConfigServer_LDADD += $(libmqmsgque_addon_LIBADD) $(liblcconfig_addon_LIBADD) $(libmkkernel_addon_LIBADD)
else
ConfigServer_LDFLAGS = $(UBSAN) -no-undefined
endif

INDEX

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

The MkKernel project is an infrastructure that link an library-item with a Target-Programming-Language using the Programming-Language-Micro-Kernel 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 using a language that is supported by the Programming-Language-Micro-Kernel.
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 using an api-layer generated by the token-stream-compiler of the Programming-Language-Micro-Kernel.

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

PROGRAMMING

The MkKernel is responsible for:

  • providing the startup and cleanup API
  • providing the memory and caching API
  • providing the logging, debugging and error API
  • providing basic objects like buffer, list, stream, logging, runtime and error

The LibMsgque is separted into three programming-layers:

  1. The foundation-layer, used by the MkKernel library programmer
  2. The kernel-layer, used by the Programming-Language-Micro-Kernel programmer
  3. The implementation-layer, used by the target-language programmer
foundation-layer
The foundation-layer implement the libmkkernel library and is also responsible for the quality-target of the entire project.
  • establishing and managing the library-items
  • memory-management and garbage-collection
  • error-handling
  • logging and debugging
  • written in plain C
kernel-layer
The kernel-layer implement the Programming-Language-Micro-Kernel and is also responsible to generate and maintain the target-language-API source-code.
  • implementation of the managed-object technology
  • implementation of the token-stream-compiler technology
  • written in plain C, TCL and the target-language-API
implementation-layer
The implementation-layer is the API used by the target-language-programmer.
  • written in plain target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO)
Target
!! This documentation describe the implementation-layer and target the C++ programmer. !!

PACKAGE

C-API: MkKernel_C_API - The package is the toplevel structure of the Programming-Language-Micro-Kernel

The ccmkkernel package is loaded with:

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

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

The ccmkkernel package add the following public classes into MkObjectC_C_API :

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

The ccmkkernel package add the following public types into MkObjectC_C_API :

    ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType)
    |
    |- ABSTRACT: MkDefTypeSTT (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 - The MkObjectC object known as obj or object is used as base-object type for a managed-object

libmqmsgque is also called as Programming-Language-Micro-Kernel. libmqmsgque 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 libmkkernel::MkObjectS :

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

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

MANAGED OBJECT TYPES

In Programming-Language-Micro-Kernel everything is a struct, there are type-struct(s) and instance-struct(s):

  1. A type-struct is derived from libmkkernel::MkTypeS and provide type-properties (static-properties) and type-methods (slots)
  2. A instance-struct is derived from libmkkernel::MkObjectS and provide instance-properties and instance-methods

An instance is full defined by min 4 structs and optional base-structs :

  1. instance-struct -> base-struct(s) -> object-struct (libmkkernel::MkObjectS)
  2. instance-type -> base-type(s) -> type-type (libmkkernel::MkTypeS)

The following naming-convention exist for the C-API (example: MkBufferC)

name definition
libmkkernel::MkBufferS instance-struct → This is the main-struct to define an instance
MkBufferST instance-type as specific-instance-type
MkBufferSTT instance-type as common-instance-type (cast from MkBufferST into MkTypeS) …
MkBufferC_T instance-type as specific-instance-type, useable in a class-macro as: class##_T
MkBufferC_TT instance-type as common-instance-type, useable in a class-macro as: class##_TT
libmkkernel::MK_BUF class-shortcut for struct MkBufferS *, all shortcut using the XX_YYY syntax (only for public API) …
libmkkernel::MK_BUFR reference-shortcut for struct MkBufferS, all shortcut using the XX_YYYR syntax (only for public API) …
libmkkernel::MkBufferCR instance-struct-reference same as struct MkBufferS, useable in a class-macro as: class##R
MkBufferCT_X(instance) cast from an instance into the specific-instance-type
MkBufferCTT_X(instance) cast from an instance into the common-instance-type
MkBufferCT_TT(typ) cast from an common-instance-type into an specific-instance-type
MkBufferCTT instance-type as common-instance-type for MkBufferC in the target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO)
MkBufferCT instance-type as specific-instance-type for MkBufferC in the target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO)

the struct(s) are defined as:

  1. The instance-type is a type-struct able to create an instance.
  2. The type-type is a type-struct not able to create an instance but used as super-class for a instance-type and the base-type
  3. The base-type is a type-struct and used to initialize the type-properties and type-methods (called slots).
    An instance provide methods and slots. A slot is a method predefined in the type like constructor. A list of all slots are defined in libmkkernel::MkTypeS.

    example MkBufferC : libmkkernel::MkTypeS -> libmkkernel::MkDefTypeS -> MkObjectST -> MkBufferST

  4. The instance is a link between the instance-struct, the base-struct the instance-type and the base-type.

    example MkBufferC : MkBufferST -> libmkkernel::MkBufferS <- libmkkernel::MkObjectS

  5. The base-struct is used to provide the base-instance-properties
    struct MyBaseStruct {
    union {
    struct MkObjectS obj
    } super;
    // MyBaseStruct-properties
    }
    struct MyInstanceStruct {
    union {
    struct MkObjectS obj
    struct MyBaseStruct bse
    } super;
    // MyInstanceStruct-properties
    }

To use the specific-instance-type as argument to a function or as property in a struct the common-instance-type of type libmkkernel::MkTypeS is used. To cast a specific-instance-type into a common-instance-type use:

  1. the path: type->super.typ
  2. the shortcut: MkTYP(type)->XYZ (pointer) or MkTYP_R(type).XYZ (reference)

To get the common-instance-type from the instance use:

  1. the path: instance->super.obj.type
  2. the shortcut: MkOBJ(instance)->type (pointer) or MkOBJ_R(instance).type (reference)

To get the base-type from the instance-type use:

  1. the path: instance->super.obj.type->base
  2. the shortcut: MkOBJ(instance)->type->base (pointer) or MkOBJ_R(instance).type->base (reference)

The predefined instance-type is an instance of the default-instance-type (libmkkernel::MkDefTypeS) …

struct MkRuntimeS {
...
struct MkDefTypeS _MkBufferST;
...
}

The properties and slots of the instance-type are predefined by the base-type and may be overwritten …

MkInstanceTypeInit ( MkBufferC, MkObjectC ) ;
MkTYP_R(MkBufferST).destructor = (MkDestructorF) MkBufferDelete_RT ;
MkTYP_R(MkBufferST).dup = (MkDupF) MkBufferDup_RT ;
MkTYP_R(MkBufferST).merge = (MkMergeF) MkBufferMerge_RT ;
MkTYP_R(MkBufferST).copy = (MkCopyF) MkBufferCopy_RT ;
MkTYP_R(MkBufferST).reset = (MkResetF) MkBufferReset_RT ;
MkTYP_R(MkBufferST).log = (MkLogF) MkBufferLog_RT ;
MkTYP_R(MkBufferST).toString = (MkToStringF) MkBufferToString_RT ;
#define MkBufferST
instance-type as specific-instance-type …
Definition kernel_mk.h:6255
#define MkTYP_R(x)
cast a known-managed-object into an libmkkernel::MkTypeS reference
Definition kernel_mk.h:4879

The following relationship between the three different struct exists:

  1. The instance-type and the type-type have the super-class libmkkernel::MkTypeS and the instance not.
  2. The type-type is a super-class of an instance-type.
  3. The instance-type has the 3 attributes libmkkernel::MkTypeS::objsig, libmkkernel::MkTypeS::objmask and libmkkernel::MkTypeS::objsize defined, the type-type not.
  4. The instance has access to the instance-type using the cast (example MkBufferCT_X(instance))
  5. The instance-type has access to the base using libmkkernel::MkTypeS::base and to the type using libmkkernel::MkObjectS::type.

MANAGED OBJECT PROGRAMMING

The Programming-Language-Micro-Kernel using the manged-object technology to create a class-system with libmkkernel::MkObjectS as the root-class.
The libmkkernel::MkObjectS is the FIRST and REQUIRED attribute in the super-union.

  1. The instance-type is a composition of one or more super-classes and instance-attributes.
  2. All super-classes are grouped into a annonymous union called super.
  3. Only the super-class struct MkObjectS obj is required for object-management, all other super-classes are optional.
  4. The name of the super-class like obj or buf is fix and is required by tool-macros and functions.
// instance-type: MyFeatureS
struct MyStructS {
// instance super-class
union {
struct MkObjectS obj; // 'object' instance-type (required)
struct MkBufferS buf; // 'buffer' instance-type (optional,example)
} super;
// instance attribute
int myInt; …
}

A class is a link (libmkkernel::MkObjectS::type) between:

instance-type(example: libmkkernel::MkBufferS)
type-type(example: MkBufferSTTMkDefTypeSTTMkTypeSTT)

A class is identified by the signature (libmkkernel::MkObjectS::signature) located at the FIRST int32 bits of the class-instance.

  • The managed-object supports one or more super-class using a union with struct libmkkernel::MkObjectS obj as the first attribute in the union.
  • The union is required because the managed-object share the memory with the super-class.

There are two possible "cast" operations on a managed-object :

  1. A "cast" from a pointer of unknown origin (example: libmkkernel::MK_MNG).
  2. A "cast" from an already known managed object pointer (example: libmkkernel::MK_BUS).

In (1) the "cast" is checked using the "signature" and in (2) the "cast" is simply resolved within the "super-class".

Example: "cast" a pointer into a libmkkernel::MkBufferS

  • "cast" from an unknown pointer: MK_BUF ret = MkBuf(ptr);
    • This "cast" is called an up-cast because you're upgrading the pointer (getting more information).
    • This "cast" checks the libmkkernel::MkObjectS::signature to ensure that ptr is a valid object.
    • This "cast" is checked at runtime.
  • "cast" from a managed pointer: MK_BUF ret = MkBUF(ptr);
    • This "cast" is called a down-cast because you downgrading the pointer (lose some information).
    • This "cast" uses the super-union to just return a pointer that is already available.
    • This "cast" is checked at compile time.
  • To put it simply: MkBuf ≠ MkBUF

Example from kernel_mk.h A full class example from libmkkernel::MkBufferS

struct MkBufferS {
// BEGIN-MkBufferS-super - created by 'cls_MqS.tcl -i NHI1_HOME/theKernel/libmkkernel/.libmkkernel.meta' - DO NOT change
union {
struct MkObjectS obj; // base CLASS \MkObjectS
} super;
// END-MkBufferS-super - created by 'cls_MqS.tcl -i NHI1_HOME/theKernel/libmkkernel/.libmkkernel.meta' - DO NOT change
// instance attributes
struct {
MK_NUM cursize;
enum MkTypeE type;
} var;
// instance storage
struct {
union MkBufferU first;
MK_NUM size;
bool doBufferFree;
} storage;
struct ilsS {
MK_NUM size;
MK_NUM offset;
} ils;
#define MkBufferS_ils_size 0
};
// BEGIN-MkBufferS-ClassDef - created by 'cls_MqS.tcl -i NHI1_HOME/theKernel/libmkkernel/.libmkkernel.meta' - DO NOT change
// Signature --------------------------------------------------------------
#define MkBufferC_SIGNATURE (MkObjectC_SIGNATURE ^ (1u<<10))
#define MkBufferC_MASK (((1u<<22)-1)<<10)
// Signature --------------------------------------------------------------
#define MkBufferC_X2buf(x) (x)
#define MkBufferC_X2obj(x) MkOBJ(x)
// TypeDef --------------------------------------------------------------
__parser__(ignore) typedef struct MkBufferS MkBufferCR;
__parser__(ignore) typedef const struct MkBufferS MkBufferCNR;
#define MkBufferC_T (&MK_RT_REF._MkBufferC_T)
#define MkBufferC_TT (MkTYP(MkBufferC_T))
#define MkBufferST MkBufferC_T
#define MkBufferSTT (MkTYP(MkBufferST))
#define MkBufferC_type MK_BUF
#define MkBufferCT_X(instance) ( (struct MkDefTypeS *) (MkOBJ_R(instance).type) )
#define MkBufferCTT_X(instance) (MkOBJ_R(instance).type)
#define MkBufferCT_TT(typ) ( (struct MkDefTypeS *) (typ) )
#define MkBufferC_NS MK
#define MkBufferCTT MkBufferCTT
#define MkBufferCT ( (struct MkDefTypeS *) MkBufferCTT )
// TypeCheck --------------------------------------------------------------
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wattributes"
__parser__(class=MkBufferC,static,hide)
mk_inline bool MkBufCheck (MK_MNGN mng) {
return MkSanitizeCheck(MkBufferC,mng);
}
#pragma GCC diagnostic pop
#define MkBufferC_Check(mng) MkBufCheck(mng)
// ObjectCast --------------------------------------------------------------
__parser__push__(prefix=Cast);
__parser__(class=MkBufferC,hide,static)
META_ATTRIBUTE_SANITIZE
mk_inline MK_BUF MkBuf(MK_MNG mng) {
return (MkBufCheck(mng) ? (MK_BUF)mng : NULL);
}
__parser__(ignore)
META_ATTRIBUTE_SANITIZE
mk_inline MK_BUFN MkBufN(MK_MNGN mng) {
return (MkBufCheck(mng) ? (MK_BUFN)mng : NULL);
}
#define MkBufRaise(_buf) if (!_MkCheckX(MkBufferC,_buf)) { \
MkErrorSetC_1E("'MkBufferC' hdl is NULL"); \
goto error ; \
}
#define MkBUF_R(x) (*(x)).super.buf
#define MkBUF(x) (&MkBUF_R(x))
// END-MkBufferS-ClassDef - created by 'cls_MqS.tcl -i NHI1_HOME/theKernel/libmkkernel/.libmkkernel.meta' - DO NOT change
bool MkBufCheck(MK_MNGN mng)
check libmkkernel::MkBufferS%->Mk{ObjectS::signature} …
Definition kernel_mk.h:6286
struct MkBufferS MkBufferCR
instance-struct-reference same as struct MkBufferS, useable in a class-macro as: class##R …
Definition kernel_mk.h:6247
const struct MkBufferS * MK_BUFN
class-shortcut for const struct MkBufferS *, all const shortcut using the XX_YYYC syntax (only for pu...
Definition kernel_mk.h:2928
const struct MkBufferS MkBufferCNR
const instance-struct-reference same as const struct MkBufferS, useable in a class-macro as: class##R...
Definition kernel_mk.h:6249
MK_BUFN MkBufN(MK_MNGN mng)
(const) cast a unknown-object into an libmkkernel::MkBufferS pointer or NULL if not possible
Definition kernel_mk.h:6312
#define mk_inline
Definition kernel_mk.h:2144
unsigned char MK_BINB
byte-array type data-type
Definition kernel_mk.h:2706
int32_t MK_NUM
array size data-type ('num' items in array …
Definition kernel_mk.h:2679
#define MkSanitizeCheck(_root, _m)
Definition kernel_mk.h:4412
#define MkBufferS_ils_size
ILS size
Definition kernel_mk.h:6217
#define __parser__pop__
Definition kernel_mk.h:318
#define __parser__push__(...)
Definition kernel_mk.h:317
#define __parser__(...)
Definition kernel_mk.h:314

PRIMITIVE TYPE

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

The data send from one package-item to an other package-item is focused on speed and usability. By default the data is send as binary, only if the endian changes or a string representation is required an additional transformation is done.
The data send from one package-item to an other package-item is limited to a collection of specific types, based on native C data types.
An ccmkkernel-API command with a focus on a specific type is using a type-postfix, for example MqReadC read a (C=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 native comment
Y MK_BYT 1 byte signed character
O MK_BOL 1 byte boolean value using true or false
S MK_SRT 2 byte signed short
I MK_INT 4 byte signed integer
W MK_WID 8 byte signed long long integer
F MK_FLT 4 byte float
D MK_DBL 8 byte double
B MK_BINN unsigned char array used for binary data
C MK_STR string data using a \0 at the end

The following compose-type identifier's are available:

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

Every native-data-type is encapsualted into a MkBufferC. A MkBufferC is type safe, this mean that every read to a MkBufferC have to match the data-type of the previous write. One exception is available, the cast from and to the MK_STR 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.

CLASS TYPE

C-API: MkKernel_ClassType_C_API - a collection of types using the META class definition …

TODO

POINTER TYPE

C-API: MkKernel_PointerType_C_API - 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 libmkkernel::MkBufferS:

TT type const type comment
B libmkkernel::MK_BIN libmkkernel::MK_BINN unsigned char array used for binary data (MK_BINN)
C libmkkernel::MK_STR libmkkernel::MK_STRN string data using a \0 at the end (MK_STR)

STORAGE MANAGEMENT

C-API: MkKernel_Storage_C_API - Storage Management …

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

Internal ccmkkernel distinguishes three different storage sources:

Context-Local-Storage (CLS)
CLS is tied to a specific MqContextC.
Example: the MqReadU 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 MqReadL 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 CC 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 always ensures that the storage management of ccmkkernel and the target-language is synchronized.
  5. If a FLS reference is added to another reference and this reference is also managed by the Programming-Language-Micro-Kernel, the Programming-Language-Micro-Kernel automatically ensures that the storage management is coherent, which means that the end user does not have to do anything.
  6. The FLS reference can be updated. This means that the FLS storage is being updated because the reference owner (usually a local variable) temporarily owns the FLS storage.

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

Example from server.cc "ReadL" overwrite previous "ReadL"

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

Example from server.cc "ReadL" overwrite previous "ReadL" even in an "Event-Loop"

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

Example from server.cc convert "ReadL" result into global storage using "Dup" and free later

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

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 (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO) supported by the Programming-Language-Micro-Kernel.

The *CreateTLS style function return a TLS that is unique per runtime and not unique per definition. The tlsid (0,1,2,3...) is used to distinguish the storage.

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

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

Attention
Use the *CreateTLS style function with caution in a local (controlled) context.
It is a problem if the event-loop is called like for an event or an asynchronous-service-call and if an other component of the software uses the same *CreateTLS style function with the same tlsid .

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

    void BUST () {
      auto bus = MkBufferStreamC::CreateTLS(0);
      while (ReadItemExists()) {
        bus->WriteU(ReadU());
      }
      bus->PosToStart();
      SendSTART();
      while (bus->ReadItemExists()) {
        SendU(bus->ReadU());
      }
      SendRETURN();
    }

MkKernel PACKAGE

MkKernel ENUM

enum libmkkernel::MkErrorEcollection for the different error-codes …
ErrorE_FromIntreturn the libmkkernel::MkErrorE from integer …
ErrorE_ToIntreturn the libmkkernel::MkErrorE as integer …
ErrorE_ToStringreturn the libmkkernel::MkErrorE as string …
enum libmkkernel::MkTimeoutEPredefined Timeout values …
TimeoutE_FromIntreturn the libmkkernel::MkTimeoutE from integer …
TimeoutE_ToIntreturn the libmkkernel::MkTimeoutE as integer …
TimeoutE_ToStringreturn the libmkkernel::MkTimeoutE as string …
enum libmkkernel::MkTypeEbasic data-types supported by Programming-Language-Micro-Kernel
TypeE_FromIntreturn the libmkkernel::MkTypeE from integer …
TypeE_ToIntreturn the libmkkernel::MkTypeE as integer …
TypeE_ToString

return the libmkkernel::MkTypeE as string …

MkKernel SETUP

Cleanupcleanup ccmkkernel internal memory …
Setup

setup ccmkkernel internal memory …

MkKernel DETAIL

C-API: MkKernel_C_API - The package is the toplevel structure of the Programming-Language-Micro-Kernel

The ccmkkernel package is loaded with:

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

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

The ccmkkernel package add the following public classes into MkObjectC_C_API :

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

The ccmkkernel package add the following public types into MkObjectC_C_API :

    ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType)
    |
    |- ABSTRACT: MkDefTypeSTT (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 ENUM

C-API: MkKernel_Enum_C_API - C-API: Internal - Enum definition - ccmkkernel enum definition …

MkKernel_C_API

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

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

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

enum libmkkernel::MkErrorE

TOP

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

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

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

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

TOP

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

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

TOP

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

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

TOP

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


enum libmkkernel::MkTimeoutE

TOP

Predefined Timeout values … → API: libmkkernel::MkTimeoutE

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

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

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

TOP

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

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

TOP

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

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

TOP

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


enum libmkkernel::MkTypeE

TOP

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

enum MkTypeE {
MK_BYTT = ((1 << MK_TYPE_SHIFT) | MK_TYPE_IS_1_BYTE ),
MK_BOLT = ((2 << MK_TYPE_SHIFT) | MK_TYPE_IS_1_BYTE ),
MK_SRTT = ((3 << MK_TYPE_SHIFT) | MK_TYPE_IS_2_BYTE ),
MK_INTT = ((4 << MK_TYPE_SHIFT) | MK_TYPE_IS_4_BYTE ),
MK_FLTT = ((5 << MK_TYPE_SHIFT) | MK_TYPE_IS_4_BYTE ),
MK_WIDT = ((6 << MK_TYPE_SHIFT) | MK_TYPE_IS_8_BYTE ),
MK_DBLT = ((7 << MK_TYPE_SHIFT) | MK_TYPE_IS_8_BYTE ),
MK_BINT = ((8 << MK_TYPE_SHIFT) ),
MK_STRT = ((9 << MK_TYPE_SHIFT) ),
MK_LSTT = ((10 << MK_TYPE_SHIFT) ),
};
#define MK_TYPE_IS_8_BYTE
the type is native and has a size of 8 bytes …
Definition kernel_mk.h:3282
#define MK_TYPE_IS_4_BYTE
the type is native and has a size of 4 bytes …
Definition kernel_mk.h:3279
#define MK_TYPE_IS_1_BYTE
the type is native and has a size of 1 byte …
Definition kernel_mk.h:3273
#define MK_TYPE_SHIFT
FIXED: type is only 8bit -> 4 bit=15 for type and 4 bit for flag …
Definition kernel_mk.h:3289
#define MK_TYPE_IS_2_BYTE
the type is native and has a size of 2 bytes …
Definition kernel_mk.h:3276
See also
TypeE_ToString, TypeE_ToInt, TypeE_FromInt, BufferGetType2, BufferCastTo, BufferStreamReadGetNextType

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

TOP

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

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

TOP

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

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

TOP

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

MkKernel SETUP

C-API: MkKernel_Setup_C_API - Setup und Cleanup the ccmkkernel

Initializing a ccmkkernel library depends on the target language and the specific nature of the Programming-Language-Micro-Kernel.

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 ccmkkernel library is initialized with Setup and released again with Cleanup. Both functions are automatically called upon loading and unloading of the shared library.

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

MK_EXTERN void MK_DECL MkSetup (void) __attribute__ ((constructor(200)));
MK_EXTERN void MK_DECL MkCleanup (void) __attribute__ ((destructor(200)));
#define MK_DECL
Definition kernel_mk.h:2157
#define MK_EXTERN
static library
Definition kernel_mk.h:2557

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

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

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

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

Example: Start of the ConfigServer application from the example/csharp directory

  • The problem with the ConfigServer 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<ConfigServer>.Add().New();
try {
srv.LinkCreate(argv);
srv.ProcessEvent(MqWaitOnEventE.FOREVER);
} catch (Exception e) {
srv.ErrorCatch(e);
}
srv.Exit();
}

[static] MkKernel::Cleanup()

TOP

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

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

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

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

[static] MkKernel::Setup()

TOP

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

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

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


MkObjectC

MkObjectC DBG

DbgMdebug: write a static-marker to the MkLogFileC (default: stderr) …
DbgDumpdebug: Dump a instance to stderr with LNG and MQ internal data…
DbgLdebug: write a instance-marker to the MkLogFileC (default: stderr) using the fmtobj as prefix …
DbgLogCdebug: write a short-obj-summary to MkLogFileC (default: stderr) …
DbgOidebug: write the object-details to MkLogFileC (default: stderr) …
DbgSTACK

debug: write the stack-trace to MkLogFileC (default: stderr) …

MkObjectC INTROSPECTION

Instancesget head-instance from linked-list of libmkkernel::MkObjectS type …
Nextget next instance from linked-list of libmkkernel::MkObjectS type
Prev

get previous instance from linked-list of libmkkernel::MkObjectS type

MkObjectC LOG

LogCwrite a logging-message to MkLogFileC (default: stderr) using the internal format …
LogHEXlog binaray data as HEX into the MkLogFileC (default: stderr) …
LogVwrite a printf style logging-message to MkLogFileC (default: stderr) using the internal format …
LogVLwrite a vprintf style logging-message to MkLogFileC using the internal format …
LogLog-Slot - log the entire object to the MkLogFileC (default: stderr) target …
LogDetaillog the libmkkernel::MkObjectS verbose into the MkLogFileC (default: stderr) …
LogSimple

log the libmkkernel::MkObjectS into the MkLogFileC (default: stderr) …

MkObjectC MISC

FromHandleImport-Slot - returns a obj from a former exported handle
ErrorCatchconvert a programming-language-error into an ccmkkernel error …
ToErrorError-Slot - return an error-object pre initialized with obj data.
ToHandleExport-Slot - returns a reference to the obj useable for external storage
ToNameInfo-Slot - returns brief information about the obj as a string
ToNameOfClassClass-Slot - returns the CC-Class-Name of the obj as string
ToNameOfTypeType-Slot - returns the LibMkKernel-Type-Name of the obj as a string
ToString

String-Slot - returns the string representation of the obj

MkObjectC TOR

DeleteDelete-Slot - delete an instance.
Dispose

Dispose-Slot - untie the connection between the Native-CC-Instance and the LibMsgque-Instance.

MkObjectC DETAIL

C-API: MkObjectC_C_API - The MkObjectC object known as obj or object is used as base-object type for a managed-object

libmqmsgque is also called as Programming-Language-Micro-Kernel. libmqmsgque 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 libmkkernel::MkObjectS :

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

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

MANAGED OBJECT TYPES

In Programming-Language-Micro-Kernel everything is a struct, there are type-struct(s) and instance-struct(s):

  1. A type-struct is derived from libmkkernel::MkTypeS and provide type-properties (static-properties) and type-methods (slots)
  2. A instance-struct is derived from libmkkernel::MkObjectS and provide instance-properties and instance-methods

An instance is full defined by min 4 structs and optional base-structs :

  1. instance-struct -> base-struct(s) -> object-struct (libmkkernel::MkObjectS)
  2. instance-type -> base-type(s) -> type-type (libmkkernel::MkTypeS)

The following naming-convention exist for the C-API (example: MkBufferC)

name definition
libmkkernel::MkBufferS instance-struct → This is the main-struct to define an instance
MkBufferST instance-type as specific-instance-type
MkBufferSTT instance-type as common-instance-type (cast from MkBufferST into MkTypeS) …
MkBufferC_T instance-type as specific-instance-type, useable in a class-macro as: class##_T
MkBufferC_TT instance-type as common-instance-type, useable in a class-macro as: class##_TT
libmkkernel::MK_BUF class-shortcut for struct MkBufferS *, all shortcut using the XX_YYY syntax (only for public API) …
libmkkernel::MK_BUFR reference-shortcut for struct MkBufferS, all shortcut using the XX_YYYR syntax (only for public API) …
libmkkernel::MkBufferCR instance-struct-reference same as struct MkBufferS, useable in a class-macro as: class##R
MkBufferCT_X(instance) cast from an instance into the specific-instance-type
MkBufferCTT_X(instance) cast from an instance into the common-instance-type
MkBufferCT_TT(typ) cast from an common-instance-type into an specific-instance-type
MkBufferCTT instance-type as common-instance-type for MkBufferC in the target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO)
MkBufferCT instance-type as specific-instance-type for MkBufferC in the target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO)

the struct(s) are defined as:

  1. The instance-type is a type-struct able to create an instance.
  2. The type-type is a type-struct not able to create an instance but used as super-class for a instance-type and the base-type
  3. The base-type is a type-struct and used to initialize the type-properties and type-methods (called slots).
    An instance provide methods and slots. A slot is a method predefined in the type like constructor. A list of all slots are defined in libmkkernel::MkTypeS.

    example MkBufferC : libmkkernel::MkTypeS -> libmkkernel::MkDefTypeS -> MkObjectST -> MkBufferST

  4. The instance is a link between the instance-struct, the base-struct the instance-type and the base-type.

    example MkBufferC : MkBufferST -> libmkkernel::MkBufferS <- libmkkernel::MkObjectS

  5. The base-struct is used to provide the base-instance-properties
    struct MyBaseStruct {
    union {
    struct MkObjectS obj
    } super;
    // MyBaseStruct-properties
    }
    struct MyInstanceStruct {
    union {
    struct MkObjectS obj
    struct MyBaseStruct bse
    } super;
    // MyInstanceStruct-properties
    }

To use the specific-instance-type as argument to a function or as property in a struct the common-instance-type of type libmkkernel::MkTypeS is used. To cast a specific-instance-type into a common-instance-type use:

  1. the path: type->super.typ
  2. the shortcut: MkTYP(type)->XYZ (pointer) or MkTYP_R(type).XYZ (reference)

To get the common-instance-type from the instance use:

  1. the path: instance->super.obj.type
  2. the shortcut: MkOBJ(instance)->type (pointer) or MkOBJ_R(instance).type (reference)

To get the base-type from the instance-type use:

  1. the path: instance->super.obj.type->base
  2. the shortcut: MkOBJ(instance)->type->base (pointer) or MkOBJ_R(instance).type->base (reference)

The predefined instance-type is an instance of the default-instance-type (libmkkernel::MkDefTypeS) …

struct MkRuntimeS {
...
struct MkDefTypeS _MkBufferST;
...
}

The properties and slots of the instance-type are predefined by the base-type and may be overwritten …

MkInstanceTypeInit ( MkBufferC, MkObjectC ) ;
MkTYP_R(MkBufferST).destructor = (MkDestructorF) MkBufferDelete_RT ;
MkTYP_R(MkBufferST).dup = (MkDupF) MkBufferDup_RT ;
MkTYP_R(MkBufferST).merge = (MkMergeF) MkBufferMerge_RT ;
MkTYP_R(MkBufferST).copy = (MkCopyF) MkBufferCopy_RT ;
MkTYP_R(MkBufferST).reset = (MkResetF) MkBufferReset_RT ;
MkTYP_R(MkBufferST).log = (MkLogF) MkBufferLog_RT ;
MkTYP_R(MkBufferST).toString = (MkToStringF) MkBufferToString_RT ;

The following relationship between the three different struct exists:

  1. The instance-type and the type-type have the super-class libmkkernel::MkTypeS and the instance not.
  2. The type-type is a super-class of an instance-type.
  3. The instance-type has the 3 attributes libmkkernel::MkTypeS::objsig, libmkkernel::MkTypeS::objmask and libmkkernel::MkTypeS::objsize defined, the type-type not.
  4. The instance has access to the instance-type using the cast (example MkBufferCT_X(instance))
  5. The instance-type has access to the base using libmkkernel::MkTypeS::base and to the type using libmkkernel::MkObjectS::type.

MANAGED OBJECT PROGRAMMING

The Programming-Language-Micro-Kernel using the manged-object technology to create a class-system with libmkkernel::MkObjectS as the root-class.
The libmkkernel::MkObjectS is the FIRST and REQUIRED attribute in the super-union.

  1. The instance-type is a composition of one or more super-classes and instance-attributes.
  2. All super-classes are grouped into a annonymous union called super.
  3. Only the super-class struct MkObjectS obj is required for object-management, all other super-classes are optional.
  4. The name of the super-class like obj or buf is fix and is required by tool-macros and functions.
// instance-type: MyFeatureS
struct MyStructS {
// instance super-class
union {
struct MkObjectS obj; // 'object' instance-type (required)
struct MkBufferS buf; // 'buffer' instance-type (optional,example)
} super;
// instance attribute
int myInt; …
}

A class is a link (libmkkernel::MkObjectS::type) between:

instance-type(example: libmkkernel::MkBufferS)
type-type(example: MkBufferSTTMkDefTypeSTTMkTypeSTT)

A class is identified by the signature (libmkkernel::MkObjectS::signature) located at the FIRST int32 bits of the class-instance.

  • The managed-object supports one or more super-class using a union with struct libmkkernel::MkObjectS obj as the first attribute in the union.
  • The union is required because the managed-object share the memory with the super-class.

There are two possible "cast" operations on a managed-object :

  1. A "cast" from a pointer of unknown origin (example: libmkkernel::MK_MNG).
  2. A "cast" from an already known managed object pointer (example: libmkkernel::MK_BUS).

In (1) the "cast" is checked using the "signature" and in (2) the "cast" is simply resolved within the "super-class".

Example: "cast" a pointer into a libmkkernel::MkBufferS

  • "cast" from an unknown pointer: MK_BUF ret = MkBuf(ptr);
    • This "cast" is called an up-cast because you're upgrading the pointer (getting more information).
    • This "cast" checks the libmkkernel::MkObjectS::signature to ensure that ptr is a valid object.
    • This "cast" is checked at runtime.
  • "cast" from a managed pointer: MK_BUF ret = MkBUF(ptr);
    • This "cast" is called a down-cast because you downgrading the pointer (lose some information).
    • This "cast" uses the super-union to just return a pointer that is already available.
    • This "cast" is checked at compile time.
  • To put it simply: MkBuf ≠ MkBUF

Example from kernel_mk.h A full class example from libmkkernel::MkBufferS

struct MkBufferS {
// BEGIN-MkBufferS-super - created by 'cls_MqS.tcl -i NHI1_HOME/theKernel/libmkkernel/.libmkkernel.meta' - DO NOT change
union {
struct MkObjectS obj; // base CLASS \MkObjectS
} super;
// END-MkBufferS-super - created by 'cls_MqS.tcl -i NHI1_HOME/theKernel/libmkkernel/.libmkkernel.meta' - DO NOT change
// instance attributes
struct {
MK_NUM cursize;
enum MkTypeE type;
} var;
// instance storage
struct {
union MkBufferU first;
MK_NUM size;
bool doBufferFree;
} storage;
struct ilsS {
MK_NUM size;
MK_NUM offset;
} ils;
#define MkBufferS_ils_size 0
};
// BEGIN-MkBufferS-ClassDef - created by 'cls_MqS.tcl -i NHI1_HOME/theKernel/libmkkernel/.libmkkernel.meta' - DO NOT change
// Signature --------------------------------------------------------------
#define MkBufferC_SIGNATURE (MkObjectC_SIGNATURE ^ (1u<<10))
#define MkBufferC_MASK (((1u<<22)-1)<<10)
// Signature --------------------------------------------------------------
#define MkBufferC_X2buf(x) (x)
#define MkBufferC_X2obj(x) MkOBJ(x)
// TypeDef --------------------------------------------------------------
__parser__(ignore) typedef struct MkBufferS MkBufferCR;
__parser__(ignore) typedef const struct MkBufferS MkBufferCNR;
#define MkBufferC_T (&MK_RT_REF._MkBufferC_T)
#define MkBufferC_TT (MkTYP(MkBufferC_T))
#define MkBufferST MkBufferC_T
#define MkBufferSTT (MkTYP(MkBufferST))
#define MkBufferC_type MK_BUF
#define MkBufferCT_X(instance) ( (struct MkDefTypeS *) (MkOBJ_R(instance).type) )
#define MkBufferCTT_X(instance) (MkOBJ_R(instance).type)
#define MkBufferCT_TT(typ) ( (struct MkDefTypeS *) (typ) )
#define MkBufferC_NS MK
#define MkBufferCTT MkBufferCTT
#define MkBufferCT ( (struct MkDefTypeS *) MkBufferCTT )
// TypeCheck --------------------------------------------------------------
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wattributes"
__parser__(class=MkBufferC,static,hide)
mk_inline bool MkBufCheck (MK_MNGN mng) {
return MkSanitizeCheck(MkBufferC,mng);
}
#pragma GCC diagnostic pop
#define MkBufferC_Check(mng) MkBufCheck(mng)
// ObjectCast --------------------------------------------------------------
__parser__push__(prefix=Cast);
__parser__(class=MkBufferC,hide,static)
META_ATTRIBUTE_SANITIZE
mk_inline MK_BUF MkBuf(MK_MNG mng) {
return (MkBufCheck(mng) ? (MK_BUF)mng : NULL);
}
__parser__(ignore)
META_ATTRIBUTE_SANITIZE
mk_inline MK_BUFN MkBufN(MK_MNGN mng) {
return (MkBufCheck(mng) ? (MK_BUFN)mng : NULL);
}
#define MkBufRaise(_buf) if (!_MkCheckX(MkBufferC,_buf)) { \
MkErrorSetC_1E("'MkBufferC' hdl is NULL"); \
goto error ; \
}
#define MkBUF_R(x) (*(x)).super.buf
#define MkBUF(x) (&MkBUF_R(x))
// END-MkBufferS-ClassDef - created by 'cls_MqS.tcl -i NHI1_HOME/theKernel/libmkkernel/.libmkkernel.meta' - DO NOT change

MkObjectC DBG

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

This functions are "helpers" to support the programmer.

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

TOP

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

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

TOP

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

Attention
this is only implemented by the Target-Programming-Language

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

TOP

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

The marker is prefixed with object data from th fmtobj.

obj.DbgLogC(MK_STRN callfunc = __builtin_FUNCTION())

TOP

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

obj.DbgO(MK_STRN callfunc = __builtin_FUNCTION())

TOP

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

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

This function can be overwritten in the target programming language.

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

TOP

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

MkObjectC INTROSPECTION

C-API: MkObjectC_Introspection_C_API - Get information from the libmkkernel::MkTypeS.

Get information about all instances created by class

The Introspection API is used to get information about the details of the instance and type implementation. Only the connection between type and instance is currently implemented.

Three methods are used to create an iteration over all avaialable instances of a type.

  • Every class has a Linked-List of all instances created starting from last to first.
  • The Introspection support always 3 Functions per class: Instance (static), Next and Prev
  • The Instance (example: [static] MkBufferC* MkBufferC::Instances())
    • return the last-instance created or NULL if no instance was created.
  • The Next (example: MkBufferC* buf.Next())
    • return the next-instance for a given-instance or NULL if the given-instance is the last-instance.
  • The Prev (example: MkBufferC* buf.Prev())
    • return the previous-instance for a given-instance or NULL if the given-instance is the first-instance.

Example: a simple loop over all instances of class MkBufferC (language C++)

for (auto buf = MkBufferC::Instances(); buf != NULL; buf = buf->Next()) {
SendC(buf->ToString());
}

[static] MkObjectC* MkObjectC::Instances()

TOP

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

The head-instance is the last instance created.

MkObjectC* obj.Next()

TOP

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

MkObjectC* obj.Prev()

TOP

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

MkObjectC LOG

C-API: MkObjectC_Log_C_API - 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.

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]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)

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

TOP

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

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

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]messagestring to log

fmtobj.LogHEX(MK_STRN callfunc, MK_BNP data)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]datathe binary data to log

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

TOP

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

Use the format and the restrictions from LogC.

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]printfmtis a c-string used as printf like format string

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

TOP

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

Use the format and the restrictions from LogC.

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]printfmtis a c-string used as printf like format string
[in]var_lista variable argument list object

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

TOP

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

Todo:

log_doku

slot_doku

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)
See also
BufferLog, BufferListLog, BufferStreamLog, ?MkLogFileLog?, ErrorLog, RuntimeDebug, ObjectLogSimple

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)
See also
MkObjectC obj.Log(MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_INT lvl = 0)

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)
See also
MkObjectC

MkObjectC MISC

C-API: MkObjectC_Misc_C_API - Various functions related to the MkObjectC

[static] MkObjectC* MkObjectC::FromHandle(MK_LONG exporthdl)

TOP

Import-Slot - returns a obj from a former exported handle → API: ccmkkernel::MkObjectC::FromHandle

Parameters
[in]exporthdlhandle former exported with ObjectToHandle
Returns
the required handle or NULL if handle is invalid

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

TOP

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

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

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

mngx->ErrorDEFAULT()->Catch(exception)

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

	    cl[id]->SendSTART();
	    try { 
	      ProxyItem(cl[id]);
	      cl[id]->SendEND_AND_WAIT("ECOI", 5);
	    } catch (const std::exception& e) {
	      auto err = ErrorCatch (e);
	      SendI (err->GetNum());
	      SendC (err->GetText());
	      err->Reset();
	    }
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
[in]exceptionthe exception object from C++, if NULL the global exception object is used
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
Returns
the ErrorDEFAULT initialized with exception value
See also
err.Raise() err.Reset(MK_STRN callfunc = __builtin_FUNCTION(), MK_INT callline = __builtin_LINE(), MK_BOOL force = false)

MkErrorC* obj.ToError()

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
Returns
the error-object
Attention
The memory of the out-value belongs to the called CcMkKernel function and therefore never becomes NULL. For details on the out-value, see: MkKernel_Storage_C_API.

MK_LONG obj.ToHandle()

TOP

Export-Slot - returns a reference to the obj useable for external storage → API: ccmkkernel::MkObjectC::ToHandle

A handle is a reference for an instance. A handle can be converted back into an instance using the ?Class?FromHandle syntax like [static] MkBufferListC* MkBufferListC::FromHandle(MK_LONG exporthdl)

Parameters
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
Returns
the required handle

MK_STRN obj.ToName()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
Returns
the identification of the object as string
Attention
The memory of the out-value belongs to the called CcMkKernel function and therefore never becomes NULL. For details on the out-value, see: MkKernel_Storage_C_API.

MK_STRN obj.ToNameOfClass()

TOP

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

The Programming-Language-Micro-Kernel connect the CC language with the libmqmsgque runtime. Every class-object in CC has an conterpart as libmqmsgque type-object in the Programming-Language-Micro-Kernel.

ObjectToNameOfType returns the name of the libmqmsgque type
ObjectToNameOfClass returns the name of the CC class

MK_STRN obj.ToNameOfType()

TOP

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

The Programming-Language-Micro-Kernel connect the CC language with the LibMsgque runtime. Every class-object in CC has an conterpart as LibMsgque type-object in the Programming-Language-Micro-Kernel.

ObjectToNameOfType returns the name of the libmsgque type
ObjectToNameOfClass returns the name of the CC class
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
Returns
the name of the object-type as a string

MK_STRN obj.ToString()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe libmkkernel::MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the libmkkernel::MkObjectS API
Returns
the required string
Attention
~ The memory of the out-value belongs to the called CcMkKernel function and therefore never becomes NULL. For details on the out-value, see: MkKernel_Storage_C_API.
~ On error an empty string is returned.

MkObjectC TOR

C-API: MkObjectC_TOR_C_API - Create and Destroy a managed-object.

[destructor] obj.Delete()

TOP

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

There are two different ways to delete an instance:

ObjectDisposeto 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 SelfDeleteForce

[destructor] obj.Dispose()

TOP

Dispose-Slot - untie the connection between the Native-CC-Instance and the LibMsgque-Instance. → API: ccmkkernel::MkObjectC::Dispose

There are two different ways to delete an instance:

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

MkBufferC

MkBufferC ACCESS

AppendCappend a single string to a MkBufferC object …
AppendVappend a single string with format and ... arguments to a MkBuffer64S …
AppendVLappend a single string with format and var_list arguments to a MkBuffer64S …
Popdelete str from the MkBufferC
Pushadd str to the MkBufferC
ToObject

return the native language object from a MkBufferC

MkBufferC GET

GetTT

get a val_out from a MkBufferC

MkBufferC INFO

GetType1return the type from a MkBufferC as single character value …
GetType2return the libmkkernel::MkTypeE from a MkBufferC
GetType3return the type from a MkBufferC as single character string …
IsLocalCheck if the MkBufferC is local (temporary), not local mean global
Loglog the MkBufferC
LogS

log the short MkBufferC object data to the MkLogFileC (default: stderr) …

MkBufferC INTROSPECTION

Instancesget head-instance from linked-list of libmkkernel::MkBufferS type …
Nextget next instance from linked-list of libmkkernel::MkBufferS type
Prev

get previous instance from linked-list of libmkkernel::MkBufferS type

MkBufferC MISC

CastTochange the type of an MkBufferC to type
Cmpcompare TWO MkBufferC objects like strcmp do it for strings …
Copycopy the MkBufferC from srce to dest
Resetreset a MkBufferC to the length zero …
ResetFullreset a MkBufferC to the length zero and free allocated storage…
SizeAddadd size storage to the buf
SizeNewalloc min size storage to the buf
Tempcreate a temporary copy of the MkBufferC buf …
ToString

get the string representation of the buf

MkBufferC SET

SetVSet the MkBufferC to the val
SetVLSet the MkBufferC to the val
SetTT

Set the MkBufferC to the val

MkBufferC TOR

CreateConstructor - create a new MkBufferC with minimum size of internal storage …
Create1024call the BufferCreate with default type libmkkernel::MkBuffer1024S (1024 byte) …
Create256call the BufferCreate with default type libmkkernel::MkBuffer256S (256 byte) …
Create64call the BufferCreate with default type libmkkernel::MkBuffer64S (64 byte) …
CreateTLSsame as BufferCreate but require no cleanup
CreateTTConstructor - create a new MkBufferC with an PRIMITIVE TYPE
FromHandleImport-Slot - returns a obj from a former exported handle
DeleteDestructor - delete a MkBufferC instance …
DupDup-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 DETAIL

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

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

MkBufferC* CLASS

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

C-Kernel-Details

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

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

‍A libmkkernel::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 libmkkernel::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 ABSTRACT-CLASS libmkkernel::MkBufferS is missing the ILS-storage, the FINAL-CLASSES are:

MkBuffer64C, MkBuffer256C and MkBuffer1024C

See also
MkBufferListC, MkBufferStreamC

MkBufferC* CTOR / DTOR

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

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

      void BUF2 () {
	SendSTART();
	for (int i=0; i<3; i++) {
          // using a reference or a pointer to avoid a "copy", ReadU never return NULL
	  const MkBufferC& buf = *ReadU();
          // GetType3 is "const", return the type as "string"
	  SendC(buf.GetType3());
	  SendU(buf);
	}
	SendRETURN();
      }
See also
BufferGetType1 BufferGetType2 BufferGetType3

MkBufferC ACCESS

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

MkBufferC* buf.AppendC(MK_STRN val)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]valthe text to append to buf
Returns
the MkBufferC object with the new value

Example from server.cc read and update a MkBufferC

	  // START - ReadU - Example, read a buffer-object and append a string 
	  buf = ReadU();
	  buf.AppendC("- a really log text to overwrite the already allocated space");
	  SendU(buf);
	  SendI(ReadI()+1);

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]printfmtis a c-string used as printf like format string
Returns
the size of the string appended to the MkBuffer64S object

MK_INT buf.AppendVL(MK_FST printfmt, va_list var_list)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]printfmtis a c-string used as printf like format string
[in]var_lista variable argument list object
Returns
the size of the string appended to the MkBuffer64S object

MK_NUM buf.Pop(MK_STRN val)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
valthe text (string) to remove from buf
Returns
the size of the string removed from the MkBuffer64S object
Attention
MkBufferC have to be of type libmkkernel::MK_STRT

MK_NUM buf.Push(MK_STRN val)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
valthe text (string) to append to buf
Returns
the size of the string appended to the MkBuffer64S object
Attention
MkBufferC have to be of type libmkkernel::MK_STRT

MkBufferC* buf.ToObject()

TOP

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

MkBufferC GET

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

buf.GetTT()

The BufferGetTT provide a single function for every PRIMITIVE TYPE

returncommand

C-API :

MK_BNP buf.GetB()libmkkernel::MkBufferGetB_RT
MK_STRN buf.GetC()libmkkernel::MkBufferGetC_RT
MK_DBL buf.GetD()libmkkernel::MkBufferGetD_RT
MK_FLT buf.GetF()libmkkernel::MkBufferGetF_RT
MK_INT buf.GetI()libmkkernel::MkBufferGetI_RT
MkBufferListC* buf.GetL(MkBufferListC* val_inout = NULL)libmkkernel::MkBufferGetL_RT
MK_BOL buf.GetO()libmkkernel::MkBufferGetO_RT
MK_SRT buf.GetS()libmkkernel::MkBufferGetS_RT
MkBufferC* buf.GetU()libmkkernel::MkBufferGetU_RT
MK_WID buf.GetW()libmkkernel::MkBufferGetW_RT
MK_BYT buf.GetY()

libmkkernel::MkBufferGetY_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
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) - (nonnull)
[in]bufthe libmkkernel::MkBufferS instance to work on - (nonnull)
[out]val_outthe value to return - (nonnull)

MkBufferC INFO

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

MK_STRB buf.GetType1()

TOP

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

MK_STRB
MkBufferGetType1_RT (
MK_BUFN const buf
)
{
switch (buf->var.type) {
case MK_STRT: return 'C';
case MK_INTT: return 'I';
case MK_DBLT: return 'D';
case MK_WIDT: return 'W';
case MK_BINT: return 'B';
case MK_BYTT: return 'Y';
case MK_BOLT: return 'O';
case MK_SRTT: return 'S';
case MK_FLTT: return 'F';
case MK_LSTT: return 'L';
}
return '*';
}
#define MK_RT_ATTR_HDL_CHECK(x)
Definition kernel_mk.h:2421
#define MK_RT_ATTR_RUNTIME_CHECK_XN(x)
Definition kernel_mk.h:2424
#define MK_RT_ARGS
Definition kernel_mk.h:2365

MkTypeE buf.GetType2()

TOP

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

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

MK_STRN buf.GetType3()

TOP

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

MK_STRN
MkBufferGetType3_RT (
MK_BUFN const buf
) {
switch (buf->var.type) {
case MK_STRT: return "C";
case MK_INTT: return "I";
case MK_DBLT: return "D";
case MK_WIDT: return "W";
case MK_BINT: return "B";
case MK_BYTT: return "Y";
case MK_BOLT: return "O";
case MK_SRTT: return "S";
case MK_FLTT: return "F";
case MK_LSTT: return "L";
}
return "*";
}

MK_BOOL buf.IsLocal()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
Returns
a boolean value… yes or no

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)
See also
MkBufferC

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]varnameThe name of the argument to report
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)

MkBufferC INTROSPECTION

C-API: MkBufferC_Introspection_C_API - Get information from the libmkkernel::MkTypeS.

Get information about all instances created by class

Get information about all instances created by class

The Introspection API is used to get information about the details of the instance and type implementation. Only the connection between type and instance is currently implemented.

Three methods are used to create an iteration over all avaialable instances of a type.

  • Every class has a Linked-List of all instances created starting from last to first.
  • The Introspection support always 3 Functions per class: Instance (static), Next and Prev
  • The Instance (example: [static] MkBufferC* MkBufferC::Instances())
    • return the last-instance created or NULL if no instance was created.
  • The Next (example: MkBufferC* buf.Next())
    • return the next-instance for a given-instance or NULL if the given-instance is the last-instance.
  • The Prev (example: MkBufferC* buf.Prev())
    • return the previous-instance for a given-instance or NULL if the given-instance is the first-instance.

Example: a simple loop over all instances of class MkBufferC (language C++)

for (auto buf = MkBufferC::Instances(); buf != NULL; buf = buf->Next()) {
SendC(buf->ToString());
}

[static] MkBufferC* MkBufferC::Instances()

TOP

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

The head-instance is the last instance created.

MkBufferC* buf.Next()

TOP

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

MkBufferC* buf.Prev()

TOP

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

MkBufferC MISC

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

buf.CastTo(MkTypeE typ)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]typcast buf to typ
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

MK_INT buf1.Cmp(const MkBufferC* buf2)

TOP

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

-# if both types are equal than the native types are compared

  1. if both types are non-equal than the string representation of the types are compared
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]buf1the FIRST MkBufferC object to compare
[in]buf2the SECOND MkBufferC object to compare
Returns
Returns < 0 if buf1 is less than buf2; > 0 if buf1 is greater than buf2, and 0 if they are equal.

MkBufferC* buf.Copy(const MkBufferC* srce)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
srcesource of the copy
Returns
the dest object

buf.Reset()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
See also
buf.ResetFull()

buf.ResetFull()

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
See also
buf.Reset()

MkBufferC* buf.SizeAdd(MK_NUM size)

TOP

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

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

MkBufferC* buf.SizeNew(MK_NUM size)

TOP

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

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

MkBufferC* buf.Temp()

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::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
The memory of the out-value belongs to the called CcMkKernel function and therefore never becomes NULL. For details on the out-value, see: MkKernel_Storage_C_API.

MK_STRN buf.ToString()

TOP

get the string representation of the buf … → API: ccmkkernel::MkBufferC::ToString

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
Returns
the required string
Attention
~ The returned string is owned by self… do not free.
~ On error an empty string is returned.

MkBufferC SET

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

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

TOP

Set the MkBufferC to the val … → API: ccmkkernel::MkBufferC::SetV

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

Returns
the libmkkernel::MkBufferS object
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]valthe value to set the buf to
Precondition
val is from type c-string used as printf like format string

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

TOP

Set the MkBufferC to the val … → API: ccmkkernel::MkBufferC::SetVL

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

Returns
the libmkkernel::MkBufferS object
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]valthe value to set the buf to
[in]var_lista variable argument list object
Precondition
val is a c-string used as printf like format string

buf.SetTT(MK_BYT val)

The BufferSetTT provide a single function for every PRIMITIVE TYPE

returncommand

C-API :

MkBufferC* buf.SetB(MK_BNP val)libmkkernel::MkBufferSetB_RT
MkBufferC* buf.SetC(MK_STRN val)libmkkernel::MkBufferSetC_RT
MkBufferC* buf.SetD(MK_DBL val)libmkkernel::MkBufferSetD_RT
MkBufferC* buf.SetF(MK_FLT val)libmkkernel::MkBufferSetF_RT
MkBufferC* buf.SetI(MK_INT val)libmkkernel::MkBufferSetI_RT
MkBufferC* buf.SetO(MK_BOL val)libmkkernel::MkBufferSetO_RT
MkBufferC* buf.SetS(MK_SRT val)libmkkernel::MkBufferSetS_RT
MkBufferC* buf.SetU(const MkBufferC* val)libmkkernel::MkBufferSetU_RT
MkBufferC* buf.SetW(MK_WID val)libmkkernel::MkBufferSetW_RT
MkBufferC* buf.SetY(MK_BYT val)

libmkkernel::MkBufferSetY_RT

Set the MkBufferC to the val

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

Returns
the libmkkernel::MkBufferS object
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
[in]valthe value to set the buf to

MkBufferC TOR

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

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

TOP

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

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]typeA type defined as libmkkernel::MkTypeS with a TT postfix (default: libmkkernel::MkBuffer64S, possible: libmkkernel::MkBuffer64S, libmkkernel::MkBuffer256S and libmkkernel::MkBuffer1024S)
[in]sizeThe 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 MqReadU

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

TOP

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

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

TOP

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

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

TOP

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

[constructor] MkBufferC::CreateTLS(MK_INT tlsid)

TOP

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

A TLS-instance only exists ONCE per thread and per TLS-function in memory. The memory will be reused and must not be freed.

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]tlsidAn per-thread unique name (integer > 0) to identify the reuse-able instance-storage. The tlsid have to be between: 0 <= tlsid < 32
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 libmkkernel::MkBufferCreateTLS_T for non-C programming languages.
Attention
for usage of the TLS-storage read more at StorageCreateTLS

[static] MkBufferC* MkBufferC::FromHandle(MK_LONG exporthdl)

TOP

Import-Slot - returns a obj from a former exported handle → API: ccmkkernel::MkBufferC::FromHandle

Parameters
[in]exporthdlhandle former exported with ObjectToHandle
Returns
the required handle or NULL if handle is invalid

[destructor] buf.Delete()

TOP

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

There are two different ways to delete an instance:

ObjectDisposeto 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 SelfDeleteForce
See also
BufferCreate BufferDup MqReadU

[constructor] buf.Dup()

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
Returns
The newly created MkBufferC instance, the instance is owned by the caller
See also
ObjDup BufferDelete

[constructor] buf.Merge()

TOP

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

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe libmkkernel::MkBufferS instance to work on
Returns
The new instance or 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] MkBufferC::CreateTT(MK_BYT val)

The BufferCreateTT provide a single function for every PRIMITIVE TYPE

returncommand

C-API :

[constructor] MkBufferC::CreateB(MK_BNP val)libmkkernel::MkBufferCreateB_RT
[constructor] MkBufferC::CreateC(MK_STRN val)libmkkernel::MkBufferCreateC_RT
[constructor] MkBufferC::CreateD(MK_DBL val)libmkkernel::MkBufferCreateD_RT
[constructor] MkBufferC::CreateF(MK_FLT val)libmkkernel::MkBufferCreateF_RT
[constructor] MkBufferC::CreateI(MK_INT val)libmkkernel::MkBufferCreateI_RT
[constructor] MkBufferC::CreateO(MK_BOL val)libmkkernel::MkBufferCreateO_RT
[constructor] MkBufferC::CreateS(MK_SRT val)libmkkernel::MkBufferCreateS_RT
[constructor] MkBufferC::CreateU(const MkBufferC* val)libmkkernel::MkBufferCreateU_RT
[constructor] MkBufferC::CreateW(MK_WID val)libmkkernel::MkBufferCreateW_RT
[constructor] MkBufferC::CreateY(MK_BYT val)

libmkkernel::MkBufferCreateY_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]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]valthe PRIMITIVE TYPE object as data-source

MkBufferStreamC

MkBufferStreamC INTROSPECTION

Instancesget head-instance from linked-list of libmkkernel::MkBufferStreamS type …
Nextget next instance from linked-list of libmkkernel::MkBufferStreamS type
Prev

get previous instance from linked-list of libmkkernel::MkBufferStreamS type

MkBufferStreamC MISC

Copycopy the MkBufferStreamC from src to bus
Loglog the MkBufferStreamC
PosToStartset the current-access-position to the start of MkBufferStreamC
Resetreset a MkBufferStreamC to the length zero …
ResetFull

reset a MkBufferStreamC to the length zero and free allocated storage…

MkBufferStreamC READ

ReadALLget a temporary MkBufferListC from all data in the MkBufferStreamC
ReadGetNextTypeget the type (libmkkernel::MkTypeE) of the next Item in the MkBufferStreamC or "0" if not available
ReadGetNumItemsget the number of items left in the MkBufferStreamC
ReadItemExistscheck if an item exists in the read-data-package
ReadLONGread the long native object from the MkBufferStreamC
ReadL_ENDEND read a list-item-type from the MkBufferStreamC
ReadL_STARTSTART read a list-item-type from the MkBufferStreamC
ReadUndoundo the last MkBufferStreamC READ function call …
ReadTT

read a val_out from the MkBufferStreamC

MkBufferStreamC TOR

Createcreate and initialize an MkBufferStreamC instance …
Create1024call the BufferStreamCreate with default type libmkkernel::MkBufferStream1024S (1024 byte) …
Create16384call the BufferStreamCreate with default type libmkkernel::MkBufferStream16384S (16384 byte) …
Create256call the BufferStreamCreate with default type libmkkernel::MkBufferStream256S (256 byte) …
Create64call the BufferStreamCreate with default type libmkkernel::MkBufferStream64S (64 byte) …
CreateTLSsame as BufferStreamCreate but require no cleanup …
FromHandleImport-Slot - returns a obj from a former exported handle
DeleteDestructor - delete a MkBufferStreamC instance …
DupDup-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 WRITE

WriteLONGwrite the long native object into the MkBufferStreamC
WriteL_ENDEND write a list-item-type into the MkBufferStreamC
WriteL_FLATwrite a MkBufferListC FLAT into the MkBufferStreamC
WriteL_STARTSTART write a list-item-type into the MkBufferStreamC
WriteVwrite format-string into the MkBufferStreamC
WriteVLwrite format-string into the MkBufferStreamC
WriteTT

write a PRIMITIVE TYPE into the MkBufferStreamC

MkBufferStreamC DETAIL

C-API: MkBufferStreamC_C_API - The MkBufferStreamC object known as bus or stream is a subclass of MkBufferC 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 libmkkernel::MkBufferStreamS has the private-parent-class libmkkernel::MkBufferS and is used to store typed-data in a continuous binary-array at libmkkernel::MkBufferS::storage.

private-parent-class mean:
libmkkernel::MkBufferStreamS use the features of libmkkernel::MkBufferS but does not expose the API

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

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

The libmkkernel::MkBufferStreamS inherits the following features from libmkkernel::MkBufferS:

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

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

libmkkernel::MkBufferStream16384S, libmkkernel::MkBufferStream256S, libmkkernel::MkBufferStream64S and libmkkernel::MkBufferStream1024S

See also
MkBufferC, MkBufferListC

MkBufferStreamC INTROSPECTION

C-API: MkBufferStreamC_Introspection_C_API - Get information from the libmkkernel::MkTypeS.

Get information about all instances created by class

Get information about all instances created by class

The Introspection API is used to get information about the details of the instance and type implementation. Only the connection between type and instance is currently implemented.

Three methods are used to create an iteration over all avaialable instances of a type.

  • Every class has a Linked-List of all instances created starting from last to first.
  • The Introspection support always 3 Functions per class: Instance (static), Next and Prev
  • The Instance (example: [static] MkBufferC* MkBufferC::Instances())
    • return the last-instance created or NULL if no instance was created.
  • The Next (example: MkBufferC* buf.Next())
    • return the next-instance for a given-instance or NULL if the given-instance is the last-instance.
  • The Prev (example: MkBufferC* buf.Prev())
    • return the previous-instance for a given-instance or NULL if the given-instance is the first-instance.

Example: a simple loop over all instances of class MkBufferC (language C++)

for (auto buf = MkBufferC::Instances(); buf != NULL; buf = buf->Next()) {
SendC(buf->ToString());
}

[static] MkBufferStreamC* MkBufferStreamC::Instances()

TOP

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

The head-instance is the last instance created.

MkBufferStreamC* bus.Next()

TOP

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

MkBufferStreamC* bus.Prev()

TOP

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

MkBufferStreamC MISC

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

MkBufferStreamC* bus.Copy(const MkBufferStreamC* src)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
srcsource of the copy
Returns
the bus instance

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

bus.PosToStart()

TOP

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

bus.Reset()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
See also
bus.ResetFull()

bus.ResetFull()

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
See also
bus.Reset()

MkBufferStreamC READ

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

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

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

TOP

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

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]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
[in,out]val_inoutthe MkBufferListC - the storage of the input is reused
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
See also
BufferStreamReadL
Attention
The memory of the out-value belongs to the called CcMkKernel function and therefore never becomes NULL. For details on the out-value, see: MkKernel_Storage_C_API.

MkTypeE bus.ReadGetNextType()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
Returns
the type

MK_NUM bus.ReadGetNumItems()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
Returns
the number of items as integer

MK_BOOL bus.ReadItemExists()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
Returns
boolean, true or false

MK_LONG bus.ReadLONG()

TOP

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

on 64bit use a BufferStreamReadI and on 32bit use a BufferStreamReadW

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
[out]val_outthe native long object to read
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
this api-function is NOT portable
See also
bus.WriteLONG(MK_LONG val)

bus.ReadL_END()

TOP

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

bus.ReadL_START(MkBufferC* buf = NULL)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
[in]bufNULL or a MkBufferC with a list-item-type or an error is raised.
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

bus.ReadUndo()

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

bus.ReadTT()

The BufferStreamReadTT provide a single function for every PRIMITIVE TYPE

returncommand

C-API :

MK_BNP bus.ReadB()libmkkernel::MkBufferStreamReadB_RT
MK_STRN bus.ReadC()libmkkernel::MkBufferStreamReadC_RT
MK_DBL bus.ReadD()libmkkernel::MkBufferStreamReadD_RT
MK_FLT bus.ReadF()libmkkernel::MkBufferStreamReadF_RT
MK_INT bus.ReadI()libmkkernel::MkBufferStreamReadI_RT
MkBufferListC* bus.ReadL()libmkkernel::MkBufferStreamReadL_RT
MK_BOL bus.ReadO()libmkkernel::MkBufferStreamReadO_RT
MkBufferC* bus.ReadU()libmkkernel::MkBufferStreamReadU_RT
MK_WID bus.ReadW()libmkkernel::MkBufferStreamReadW_RT
MK_BYT bus.ReadY()

libmkkernel::MkBufferStreamReadY_RT

read a val_out from the MkBufferStreamC

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

Precondition
The val_out can be a PRIMITIVE TYPE, a class-type or a pointer-type (binary, string etc).
After every read the current-access-position is incremented by one to get the next item for the next read.
To reset the current-access-position to the start use bus.PosToStart().
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
[out]val_outthe new value

MkBufferStreamC TOR

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

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

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]typeA type defined as libmkkernel::MkTypeS with a TT postfix (default: libmkkernel::MkBufferStream1024S, possible: libmkkernel::MkBufferStream16384S, libmkkernel::MkBufferStream256S, libmkkernel::MkBufferStream64S and libmkkernel::MkBufferStream1024S)
[in]sizeThe 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] MkBufferStreamC::Create1024(MK_NUM size = 0)

TOP

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

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

TOP

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

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

TOP

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

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

TOP

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

[constructor] MkBufferStreamC::CreateTLS(MK_NUM tlsid)

TOP

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

A TLS-instance only exists ONCE per thread and per TLS-function in memory. The memory will be reused and must not be freed.

The new BufferStreamCreateTLS instance is ready to use and does NOT require a BufferStreamReset first and a BufferStreamDelete last.

By default the libmkkernel::MkBufferStream64S type is used as an array of references (struct MkBufferStream64S and not struct MkBufferStream64S *). If the memory requirement exceed the predefined-storage of the libmkkernel::MkBufferStream64S the memory is allocated on the heap.

Example from perfserver.cc performance test with TLS storage

    void BUST () {
      auto bus = MkBufferStreamC::CreateTLS(0);
      while (ReadItemExists()) {
        bus->WriteU(ReadU());
      }
      bus->PosToStart();
      SendSTART();
      while (bus->ReadItemExists()) {
        SendU(bus->ReadU());
      }
      SendRETURN();
    }
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]tlsidAn per-thread unique name (integer > 0) to identify the reuse-able instance-storage. The tlsid have to be between: 0 <= tlsid < 32
Returns
the new MkBufferStreamC 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

[static] MkBufferStreamC* MkBufferStreamC::FromHandle(MK_LONG exporthdl)

TOP

Import-Slot - returns a obj from a former exported handle → API: ccmkkernel::MkBufferStreamC::FromHandle

Parameters
[in]exporthdlhandle former exported with ObjectToHandle
Returns
the required handle or NULL if handle is invalid

[destructor] bus.Delete()

TOP

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

There are two different ways to delete an instance:

ObjectDisposeto 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 SelfDeleteForce
See also
BufferStreamCreate BufferStreamDup

[constructor] src.Dup()

TOP

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

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

Returns
The newly created MkBufferStreamC instance, the instance is owned by the caller
See also
ObjDup BufferStreamDelete

[constructor] bus.Merge()

TOP

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

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on - (nonnull)
Returns
The new instance or 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 WRITE

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

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

bus.WriteLONG(MK_LONG val)

TOP

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

on 64bit use a BufferStreamWriteW and on 32bit use a BufferStreamWriteI

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
[in]valthe native long object to write
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
this api-function is NOT portable
See also
MK_LONG bus.ReadLONG()

bus.WriteL_END()

TOP

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

bus.WriteL_FLAT(MkBufferListC* bfl)

TOP

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

A MkBufferListC can be written into a MkBufferStreamC using:

command description example
BufferStreamWriteL 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]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
[in]bflthe MkBufferListC to insert
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
See also
BufferStreamReadL BufferStreamReadL

bus.WriteL_START()

TOP

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

bus.WriteV(MK_STRN fmt, ... )

TOP

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

bus.WriteVL(MK_STRN fmt, va_list ap)

TOP

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

bus.WriteTT(MK_BYT val)

The BufferStreamWriteTT provide a single function for every PRIMITIVE TYPE

returncommand

C-API :

bus.WriteB(MK_BNP val)libmkkernel::MkBufferStreamWriteB_RT
bus.WriteC(MK_STRN val)libmkkernel::MkBufferStreamWriteC_RT
bus.WriteD(MK_DBL val)libmkkernel::MkBufferStreamWriteD_RT
bus.WriteF(MK_FLT val)libmkkernel::MkBufferStreamWriteF_RT
bus.WriteI(MK_INT val)libmkkernel::MkBufferStreamWriteI_RT
bus.WriteL(MkBufferListC* bfl)libmkkernel::MkBufferStreamWriteL_RT
bus.WriteO(MK_BOL val)libmkkernel::MkBufferStreamWriteO_RT
bus.WriteU(MkBufferC* val)libmkkernel::MkBufferStreamWriteU_RT
bus.WriteW(MK_WID val)libmkkernel::MkBufferStreamWriteW_RT
bus.WriteY(MK_BYT val)

libmkkernel::MkBufferStreamWriteY_RT

write a PRIMITIVE TYPE into the MkBufferStreamC

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe libmkkernel::MkBufferStreamS instance to work on
[in]valthe new PRIMITIVE TYPE
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

MkBufferListC

MkBufferListC APPEND

AppendGappend a native PRIMITIVE TYPE object to a MkBufferListC
AppendLAappend a variable number of MkBufferC object's to an MkBufferListC object using an other MkBufferListC OR a list of arguments (only in NON MK_STR)
AppendLPcopy a MkBufferListS list into an MkBufferListS object on position
AppendUPappend a MkBufferC item into an MkBufferListC object on position
AppendVappend an printf like format object to the end of an MkBufferListS object …
AppendVAappend a variable number of strings to an MkBufferListS object …
AppendVALappend a variable number of strings to an MkBufferListS object …
AppendVCappend a argc/argv list of strings to an MkBufferListS object …
AppendVLappend an printf like format object to the end of an MkBufferListS object …
AppendTTappend a native PRIMITIVE TYPE object to a MkBufferListC
PositionMerge

merge a MkBufferListS list into an MkBufferListS object on position

MkBufferListC CHECK

CheckOptionsearch for boolean option in MkBufferListS list and return libmkkernel::MK_BOL value …
CheckOptionTT

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

MkBufferListC INDEX

IndexDeletedelete the index'th list item from the MkBufferListS object …
IndexExtractextract (read & delete) the index object from bfl
IndexGetget (read only) the index object from bfl
IndexGetCget the index element from MkBufferListC ... as string. …
IndexGetUget the index element from MkBufferListC ... if not available… create it. …
IndexSetset the index object from bfl
IndexSetCset the index element from MkBufferListC ... to string… if not available… create space …
IndexSetUset the index element from MkBufferListC ... if not available… createspace …
Reservereserve num items in a MkBufferListC object …
Size

get the number-of-items in the bfl

MkBufferListC INTROSPECTION

Instancesget head-instance from linked-list of libmkkernel::MkBufferListS type …
Nextget next instance from linked-list of libmkkernel::MkBufferListS type
Prev

get previous instance from linked-list of libmkkernel::MkBufferListS type

MkBufferListC LOG

Logwrite the detail-summary of the MkBufferListC to MkLogFileC (default: stderr) …
LogSwrite the short-summary of the MkBufferListC to MkLogFileC (default: stderr) …
LogSSwrite 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

Cmpcompare two buffer-list
Copycopy all internal data from src to tgt
Movemove all internal data from from to the end of to
Resetreset a MkBufferListC object …
SearchCsearch libmkkernel::MK_STR item from a MkBufferListS object starting at startindex
Sortsort a MkBufferListC
ToBufferExport a bfl into an MkBufferC using an MkBufferStreamC
ToList

get a target-language list representation of the bfl

MkBufferListC TOR

CreateConstructs a MkBufferC instance with size storage…
CreateLAConstructs a MkBufferListC instance with an other MkBufferListC OR a list of arguments (only in NON MK_STR)
CreateTLSsame as BufferListCreate but require no cleanup …
CreateVAConstructs a MkBufferListC instance with a varargs argument that ends with NULL
CreateVALConstructs a MkBufferListC instance with a va_list argument …
CreateVCConstructs a MkBufferListC instance with a argc/argv data from a list of strings …
FileGlobcreate a new MkBufferListC using the result from a filesystem glob operation …
FromHandleImport-Slot - returns a obj from a former exported handle
DeleteDestructor - delete a MkBufferListC instance …
DupDup-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 DETAIL

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

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

MkBufferListC* CLASS

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

C-Kernel-Details

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

‍0 <= index < libmkkernel::MkBufferListS::cursize

A new libmkkernel::MkBufferListS is always preallocated with the predefined ILS-storage (libmkkernel::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 libmkkernel::MkBufferListS never run out of storage.

See also
MkBufferC, MkBufferStreamC

MkBufferListC* CTOR / DTOR

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

MkBufferListC APPEND

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

bfl.AppendG(MK_LONG val)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]valthe PRIMITIVE TYPE object data to append

MkBufferListC* bfl.AppendLA(MkBufferListC* args)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]argsthe MkBufferListC object

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]addBufLthe MkBufferListS object to append
[in]positioninsert in at position, shift all following arguments one up
Attention
Set position to 0 to append to the beginning or set position to -1 to append to the end

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

TOP

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

- set position to 0 to append to the beginning

  • set position to -1 to append to the end
  • after append the addBuf belongs to bfl
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]addBufthe MkBufferC object to append
[in]positioninsert in at position, shift all following arguments one up
Attention
After append the object addBuf will be owned by bfl.

bfl.AppendV(MK_FST printfmt, ... )

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]printfmtis a c-string used as printf like format string

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]arg0anchor element for ...
Attention
The C-Api requires a NULL item on end to signal… end-of-list.

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]arg0anchor element for ...
[in]var_lista variable argument list object
Attention
The C-Api requires a NULL item on end to signal… end-of-list.

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]argcthe length of the argv array
[in]argvthe strings to append

bfl.AppendVL(MK_FST printfmt, va_list var_list)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]printfmtis a c-string used as printf like format string
[in]var_lista variable argument list object

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]sourcethe object to be merged into bfl, afterwords the source is empty and can be deleted
[in]positioninsert 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

bfl.AppendTT(MK_BYT val)

The BufferListAppendTT provide a single function for every PRIMITIVE TYPE

returncommand

C-API :

bfl.AppendC(MK_STRN val)libmkkernel::MkBufferListAppendC_RT
bfl.AppendD(MK_DBL val)libmkkernel::MkBufferListAppendD_RT
bfl.AppendF(MK_FLT val)libmkkernel::MkBufferListAppendF_RT
bfl.AppendI(MK_INT val)libmkkernel::MkBufferListAppendI_RT
bfl.AppendO(MK_BOL val)libmkkernel::MkBufferListAppendO_RT
bfl.AppendS(MK_SRT val)libmkkernel::MkBufferListAppendS_RT
bfl.AppendU(MkBufferC* val)libmkkernel::MkBufferListAppendU_RT
bfl.AppendW(MK_WID val)libmkkernel::MkBufferListAppendW_RT
bfl.AppendY(MK_BYT val)

libmkkernel::MkBufferListAppendY_RT

append a native PRIMITIVE TYPE object to a MkBufferListC

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]valthe PRIMITIVE TYPE object data to append

MkBufferListC CHECK

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

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

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

TOP

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

-# If opt is found, the opt is deleted from the MkBufferListC.

  1. If opt starting with a - or a -- the opt is treated as true
  2. If opt starting with a + or a ++ the opt is treated as false
  3. If opt does not start with a - or a + than the opt is treated as true
  4. It multiple opt are available all opt are checked and deleted.
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on or NULL
[in]optFind opt string in the MkBufferListC
[in]onlyFirstStop after first item was found

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

The BufferListCheckOptionTT provide a single function for every PRIMITIVE TYPE

returncommand

C-API :

MK_STRN bfl.CheckOptionC(MK_STRN opt, MK_STRN defval = "", MK_BOOL onlyFirst = true)libmkkernel::MkBufferListCheckOptionC_RT
MK_DBL bfl.CheckOptionD(MK_STRN opt, MK_DBL defval = 0, MK_BOOL onlyFirst = true)libmkkernel::MkBufferListCheckOptionD_RT
MK_FLT bfl.CheckOptionF(MK_STRN opt, MK_FLT defval = 0, MK_BOOL onlyFirst = true)libmkkernel::MkBufferListCheckOptionF_RT
MK_INT bfl.CheckOptionI(MK_STRN opt, MK_INT defval = 0, MK_BOOL onlyFirst = true)libmkkernel::MkBufferListCheckOptionI_RT
MK_BOOL bfl.CheckOptionO(MK_STRN opt, MK_BOOL defval = false, MK_BOOL onlyFirst = true)libmkkernel::MkBufferListCheckOptionO_RT
MK_SRT bfl.CheckOptionS(MK_STRN opt, MK_SRT defval = 0, MK_BOOL onlyFirst = true)libmkkernel::MkBufferListCheckOptionS_RT
MkBufferC* bfl.CheckOptionU(MK_STRN opt, MkBufferC* defval = NULL, MK_BOOL onlyFirst = true)libmkkernel::MkBufferListCheckOptionU_RT
MK_WID bfl.CheckOptionW(MK_STRN opt, MK_WID defval = 0, MK_BOOL onlyFirst = true)libmkkernel::MkBufferListCheckOptionW_RT
MK_BYT bfl.CheckOptionY(MK_STRN opt, MK_BYT defval = 0, MK_BOOL onlyFirst = true)

libmkkernel::MkBufferListCheckOptionY_RT

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on or NULL
[in]optFind opt string in the MkBufferListC
[in]defvalThe value used if opt was not found
[in]onlyFirstIf more than one opt is available, return only the first (true [DEFAULT]) or the last (false)
[out]val_outIf opt is found, return the argument from opt otherwise defval
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
  • If val_out is 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 - various functions to access a MkBufferListC by 'index' …

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
numitemsdelete number of items
doDeleteif doDelete == true delete the MkBufferC object, associated with the index, too
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

MkBufferC* bfl.IndexExtract(MK_NUM index = 0)

TOP

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

If the index is not available, this is an error

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
[out]val_outthe MkBuffer64S object to return
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
1. val_out is owned by the caller and have to be freed.
2. val_out will allways be set to NULL first.
See also
BufferListDelete

MkBufferC* bfl.IndexGet(MK_NUM index)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
[out]val_outthe MkBufferC to return
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
1. val_out is owned by the MkBufferListC and must NOT be freed.
2. val_out will allways be set to NULL first.
3. it is an error if index is not available.
See also
BufferListIndexGetU

MK_STRN bfl.IndexGetC(MK_NUM index)

TOP

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

for details please refer to BufferListIndexGetU.

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]indexan 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

MkBufferC* bfl.IndexGetU(MK_NUM index)

TOP

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

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]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
Returns
the MkBufferC requested
See also
BufferListIndexGet

bfl.IndexSet(MK_NUM index, MkBufferC* buf)

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
[in]bufthe libmkkernel::MkBufferS instance to work on
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
It is an error if index is not available.
See also
BufferListIndexSetU

bfl.IndexSetC(MK_NUM index, MK_STRN str)

TOP

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

for details please refer to BufferListIndexGetU

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
[in]strthe string to set

bfl.IndexSetU(MK_NUM index, MkBufferC* buf)

TOP

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

-# cursize will be >= index+1

  1. size will be >= index+1
  2. cursize <= X < index+1 -> the missing buffer will be created
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
[in]bufthe libmkkernel::MkBufferS instance to work on

bfl.Reserve(MK_NUM num)

TOP

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

-# cursize will be num

  1. size will b >= num
  2. free: num <= X < cursize
  3. init: cursize <= X < num
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
bflthe MkBufferListC object to reserve memory
numreserve the number of items for later use.

MK_NUM bfl.Size()

TOP

get the number-of-items in the bfl … → API: ccmkkernel::MkBufferListC::Size

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
Returns
the number-of-items in the bfl

MkBufferListC INTROSPECTION

C-API: MkBufferListC_Introspection_C_API - Get information from the libmkkernel::MkTypeS.

Get information about all instances created by class

Get information about all instances created by class

The Introspection API is used to get information about the details of the instance and type implementation. Only the connection between type and instance is currently implemented.

Three methods are used to create an iteration over all avaialable instances of a type.

  • Every class has a Linked-List of all instances created starting from last to first.
  • The Introspection support always 3 Functions per class: Instance (static), Next and Prev
  • The Instance (example: [static] MkBufferC* MkBufferC::Instances())
    • return the last-instance created or NULL if no instance was created.
  • The Next (example: MkBufferC* buf.Next())
    • return the next-instance for a given-instance or NULL if the given-instance is the last-instance.
  • The Prev (example: MkBufferC* buf.Prev())
    • return the previous-instance for a given-instance or NULL if the given-instance is the first-instance.

Example: a simple loop over all instances of class MkBufferC (language C++)

for (auto buf = MkBufferC::Instances(); buf != NULL; buf = buf->Next()) {
SendC(buf->ToString());
}

[static] MkBufferListC* MkBufferListC::Instances()

TOP

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

The head-instance is the last instance created.

MkBufferListC* bfl.Next()

TOP

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

MkBufferListC* bfl.Prev()

TOP

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

MkBufferListC LOG

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

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)
See also
MkBufferListC

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
varnameprefix to identify the variable name
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
varnameprefix to identify the variable name
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)

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

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]varnameThe name of the argument to report
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)

MkBufferListC MISC

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

MK_INT bfl.Cmp(const MkBufferListC* bfl2)

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]bfl2buffer-list to compare
Returns
Returns < 0 if bfl is less than bfl2; > 0 if bfl is greater than bfl2, and 0 if they are equal

bfl.Copy(const MkBufferListC* src)

TOP

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

-# existing data will be overwritten

  1. the cursize of src will be the cursize of tgt
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
[in]srcthe source of the copy

to.Move(MkBufferListC* from)

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]tothe target of the move
[in]fromthe source of the move

bfl.Reset()

TOP

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
Attention
all MkBufferC objects will be freed

MK_NUM bfl.SearchC(MK_STRN str, MK_NUM len = -1, MK_NUM startindex = 0)

TOP

search libmkkernel::MK_STR item from a MkBufferListS object starting at startindex … → API: ccmkkernel::MkBufferListC::SearchC

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
strthe string to search for
lenthe length of str or -1 to calulate the length with strlen
startindexstart 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) {
...
}
#define MkBufferListSearchC(...)
Attention
The size of str have to be at least 4 bytes

MkBufferListC* bfl.Sort()

TOP

sort a MkBufferListC … → API: ccmkkernel::MkBufferListC::Sort

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
Returns
Return the input bfl as sorted list

MkBufferC* bfl.ToBuffer()

TOP

Export a bfl into an MkBufferC using an MkBufferStreamC … → API: ccmkkernel::MkBufferListC::ToBuffer

An buffer is able to hold all primitive types and LIST of primitive types. An buffer-list is an Indexed-LIST representation of a LIST of buffer.

To add a buffer-list into an buffer the buffer-list have to be converted into a buffer-stream and the buffer-stream have to be exported as buffer. The buffer is finally apended to the buffer-list.

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
Returns
the required buffer or a NULL on error
Attention
The memory of the out-value belongs to the called CcMkKernel function and therefore never becomes NULL. For details on the out-value, see: MkKernel_Storage_C_API.

MkBufferListC* bfl.ToList()

TOP

get a target-language list representation of the bfl … → API: ccmkkernel::MkBufferListC::ToList

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
Returns
the required list
Attention
this is only implemented by the Target-Programming-Language

MkBufferListC TOR

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

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

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]sizeThe 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] MkBufferListC::CreateLA(MkBufferListC* args)

TOP

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

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

Returns
The newly created MkBufferListC instance, the instance is owned by the caller
See also
BufferListDup

[constructor] MkBufferListC::CreateTLS(MK_NUM tlsid)

TOP

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

A TLS-instance only exists ONCE per thread and per TLS-function in memory. The memory will be reused and must not be freed.

The new BufferListCreateTLS instance is ready to use and does NOT require a BufferListReset first and a BufferListDelete last.

By default a libmkkernel::MkBufferListS type is created because internal an array of references is used and no "malloc" etc is done. ONLY if the required size extend the libmkkernel::MkBufferListS prealloc size the storage-manager switch internal to dynamic storage management.

Example from perfserver.cc performance test with TLS storage

void BFLT () {
auto bfl = MkBufferListC::CreateTLS(0);
while (ReadItemExists()) {
bfl->AppendU(ReadU());
}
SendSTART();
for (MK_NUM i=0; i<bfl->Size(); ++i) {
SendU(bfl->IndexGet(i));
}
SendRETURN();
}
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]tlsidAn per-thread unique name (integer > 0) to identify the reuse-able instance-storage. The tlsid have to be between: 0 <= tlsid < 32
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] MkBufferListC::CreateVA(MK_STRN arg0, ... )

TOP

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

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

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

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

TOP

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

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

Returns
The newly created MkBufferListC instance, the instance is owned by the caller
See also
va_start(3), va_arg(3), va_copy(3), and va_end(3)

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

TOP

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
argcthe argc from the initial main function
argvthe 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);
....
}
#define MkBufferListCreateVC(...)

[constructor] MkBufferListC::FileGlob(MK_STRN pattern_match)

TOP

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

[static] MkBufferListC* MkBufferListC::FromHandle(MK_LONG exporthdl)

TOP

Import-Slot - returns a obj from a former exported handle → API: ccmkkernel::MkBufferListC::FromHandle

Parameters
[in]exporthdlhandle former exported with ObjectToHandle
Returns
the required handle or NULL if handle is invalid

[destructor] bfl.Delete()

TOP

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

There are two different ways to delete an instance:

ObjectDisposeto 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 SelfDeleteForce
See also
BufferListCreate BufferListDup MqReadL

[constructor] bfl.Dup()

TOP

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

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

Returns
The newly created MkBufferListC instance, the instance is owned by the caller
See also
ObjDup

[constructor] bfl.Merge()

TOP

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

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

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe libmkkernel::MkBufferListS instance to work on
Returns
The new instance or NULL on error or if no Merge-Constructor is available
Attention
The new instance have to be deleted with BufferListDelete
See also
BufferListDup

MkErrorC

MkErrorC GET

GetCodeget the value of libmkkernel::MkErrorS::code
GetNumget the libmkkernel::MkErrorS::num. The number can be used as exit-code …
GetSizeget the error-message-size from the exception-object
GetText

get the libmkkernel::MkErrorS::text

MkErrorC INTROSPECTION

Instancesget head-instance from linked-list of libmkkernel::MkErrorS type …
Nextget next instance from linked-list of libmkkernel::MkErrorS type
Prev

get previous instance from linked-list of libmkkernel::MkErrorS type

MkErrorC MISC

Catchconvert a programming-language-error into an ccmkkernel error …
Loglog the error to MkLogFileC (default: stderr) …
Printlnprint the default-error to the MkLogFileC (default: stderr) and clear the error afterwards …
ResetThis function clears the err and resets to libmkkernel::MK_OK
Stackcheck 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 RAISE

PanicCdo a panic with string as argument …
PanicVdo a panic with a vararg as argument …
PanicVLdo a panic with a vararg-list as argument …
AppendCappend the message to the libmkkernel::MkErrorS::text
AppendVappend a vararg string to the MkErrorC
AppendVLappend a va_list string to the MkErrorC
NoRaiseignore the next return of libmkkernel::MK_ERROR and do not raise an target-language-exception
Raiseconvert an ccmkkernel error into an programming-language-error and raise afterwards. …
SetC'set' and 'raise' the MkErrorC using a string-message and a errnum-number
SetVset the libmkkernel::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

IsEXITcheck on APPLICATION-EXIT error …
IsSOCKETcheck on SOCKET-DOWN error …
SetCONTINUEsignal end of processing in an MqIEvent callback …
SetCodeset the libmkkernel::MkErrorS::code value …
SetEXITfinish the current callback, return to toplevel and MqExit the application …
SetSOCKET

create SOCKET-DOWN error …

MkErrorC SYSTEM

DEFAULTsystem-error - this is always the error in duty …
IGNOREsystem-error - do not store the error in an MkErrorC and ignore the error …
PRINT

system-error - print the error to the MkLogFileC

MkErrorC TOR

FromHandleImport-Slot - returns a obj from a former exported handle
DeleteDestructor - delete a libmkkernel::MkErrorS object …
Dup

Dup-Constructor - create a new MkErrorC instance as copy from an existing MkErrorC instance …

MkErrorC DETAIL

C-API: MkErrorC_C_API - The MkErrorC object 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 libmkkernel::MkRuntimeRLS using the datatype MkErrorC.

‍As error-indicator the enum libmkkernel::MkErrorE is used.

The MkErrorC is used to collect all data needed to handle an error and provide global ressources required to process and report the error.

The MkErrorC is also used to integrate the error-handling from ccmkkernel into the error-handling-code of the target C++.

Example from Filter6.cc use MqContextErrorCatch to convert a C++ error into a ccmkkernel error

int MK_CDECL main (int argc, MK_STRN argv[])
{
  MqMsgque::Setup();
  // define factory
  auto Filter6F = MqFactoryCT<Filter6>::Add("Filter6");
  // modify default type
  Filter6F->Type()->fHelp = Filter6::Help;
  // create object from factory
  Filter6 *filter = Filter6F->New();
  try {
    filter->LinkCreate (MkBufferListC {argc, argv});
    filter->ProcessEvent (MQ_WAIT_FOREVER);
  } catch (const exception& e) {
    filter->ErrorCatch(e);
  }
  filter->Exit();
}

MkExceptionC

Object used to connect the LibMsgqueError with the target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO) error …

The LibMsgque 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 (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO) add their own error-handling and the purpose of MkExceptionC is to integrate the MkErrorC into the target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO).

The implementation of an exception depends heavily on the target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO), 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 (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO) without support by the Programming-Language-Micro-Kernel compiler.
  • By default, MkExceptionC is only used internally, hidden by the class MkErrorC.

ExceptionCheck

Checks if Exception is of type MkExceptionC and returns true or false

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

            MK_INT PID, RET=0;
            auto VAL = ReadU();
            Client cl;
            cl.LinkCreate(ConfigGetStartAs());
            cl.Send("W","GPID@I", &PID);
            SysKill(PID,9);
            for (int i = 0; i < 3; i++) {
              try {
                cl.Send("W","ECOI:U@I", VAL, &RET);
              } catch (const MkExceptionC &ex) {
                auto err = cl.ErrorCatch(ex);
                if (err->IsSOCKET()) {
                  err->Reset();
                  cl.LinkConnect();
                  continue;
                } else {
                  err->Raise();
                }
              }
              break;
            }
            SendSTART();
            SendI(RET);
Returns
the result of the check, true or false
Parameters
[in]exceptionthe exception object from C++, if NULL the global exception object is used

MkErrorC GET

C-API: MkErrorC_Get_C_API - various functions to 'get' data out of MkErrorC

MkErrorE err.GetCode()

TOP

get the value of libmkkernel::MkErrorS::code … → API: ccmkkernel::MkErrorC::GetCode

MK_INT err.GetNum()

TOP

get the libmkkernel::MkErrorS::num. The number can be used as exit-code … → API: ccmkkernel::MkErrorC::GetNum

MK_SIZE err.GetSize()

TOP

get the error-message-size from the exception-object … → API: ccmkkernel::MkErrorC::GetSize

MK_STRN err.GetText()

TOP

get the libmkkernel::MkErrorS::text … → API: ccmkkernel::MkErrorC::GetText

MkErrorC INTROSPECTION

C-API: MkErrorC_Introspection_C_API - Get information from the libmkkernel::MkTypeS.

Get information about all instances created by class

Get information about all instances created by class

The Introspection API is used to get information about the details of the instance and type implementation. Only the connection between type and instance is currently implemented.

Three methods are used to create an iteration over all avaialable instances of a type.

  • Every class has a Linked-List of all instances created starting from last to first.
  • The Introspection support always 3 Functions per class: Instance (static), Next and Prev
  • The Instance (example: [static] MkBufferC* MkBufferC::Instances())
    • return the last-instance created or NULL if no instance was created.
  • The Next (example: MkBufferC* buf.Next())
    • return the next-instance for a given-instance or NULL if the given-instance is the last-instance.
  • The Prev (example: MkBufferC* buf.Prev())
    • return the previous-instance for a given-instance or NULL if the given-instance is the first-instance.

Example: a simple loop over all instances of class MkBufferC (language C++)

for (auto buf = MkBufferC::Instances(); buf != NULL; buf = buf->Next()) {
SendC(buf->ToString());
}

[static] MkErrorC* MkErrorC::Instances()

TOP

get head-instance from linked-list of libmkkernel::MkErrorS type … → API: ccmkkernel::MkErrorC::Instances

The head-instance is the last instance created.

MkErrorC* err.Next()

TOP

get next instance from linked-list of libmkkernel::MkErrorS type → API: ccmkkernel::MkErrorC::Next

MkErrorC* err.Prev()

TOP

get previous instance from linked-list of libmkkernel::MkErrorS type → API: ccmkkernel::MkErrorC::Prev

MkErrorC MISC

C-API: MkErrorC_Misc_C_API - various functions to 'work' on a MkErrorC

MkErrorC* err.Catch(std::exception* exception = NULL, MK_STRN callfunc = __builtin_FUNCTION())

TOP

convert a programming-language-error into an ccmkkernel error … → API: ccmkkernel::MkErrorC::Catch

Same as MkErrorC* obj.ErrorCatch(std::exception* exception = NULL, MK_STRN callfunc = __builtin_FUNCTION()) but skip the Error-Prefix in final target-programming-language (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO).

Example from Bug3.cc catch an error using [static] MkErrorC* MkErrorC::DEFAULT(const MkObjectC* fmtobj = NULL)

  } catch (const std::exception& ex) {
    MkErrorC::DEFAULT()->Catch(ex)->Println();
  } catch (...) {
    MkErrorC::PRINT()->SetC("unknown exception");
  }
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]exceptionthe exception object from C++, if NULL the global exception object is used
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
Returns
the ErrorDEFAULT initialized with exception value
See also
err.Raise() err.Reset(MK_STRN callfunc = __builtin_FUNCTION(), MK_INT callline = __builtin_LINE(), MK_BOOL force = false)

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

TOP

log the error to MkLogFileC (default: stderr) … → API: ccmkkernel::MkErrorC::Log

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)
See also
MkErrorC err.Log(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_INT lvl = 0)

err.Println()

TOP

print the default-error to the MkLogFileC (default: stderr) and clear the error afterwards … → API: ccmkkernel::MkErrorC::Println

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)

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

TOP

This function clears the err and resets to libmkkernel::MK_OK … → API: ccmkkernel::MkErrorC::Reset

Attention
Use this function carfully, as misuse will result in the loss of the error-message.

It is recommended that you use this feature only after the error has been processed.

  • processed = The error was send to another server or printed to the user or to a file.
See also
ErrorRaise ErrorCatch

MkErrorE err.Stack(MK_STRN callfunc = __builtin_FUNCTION(), MK_STRN callfile = __builtin_FILE(), MK_INT callline = __builtin_LINE())

TOP

check on error and if yes append an ErrorStackFormat to the error-message … → API: ccmkkernel::MkErrorC::Stack

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed) → NULL allowed
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]callfilethe name of the file the call take place (e.g. FILE)
[in]calllinethe number of the line the call take place (e.g. LINE)
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

err.StackFormat(MK_STRN callfunc = __builtin_FUNCTION(), MK_STRN callfile = __builtin_FILE(), MK_INT callline = __builtin_LINE())

TOP

append an ensemble of func, file and line to the error-message … → API: ccmkkernel::MkErrorC::StackFormat

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]callfilethe name of the file the call take place (e.g. FILE)
[in]calllinethe number of the line the call take place (e.g. LINE)

MkErrorC RAISE

C-API: MkErrorC_Raise_C_API - various functions to 'raise' a MkErrorC

An error is "raised" by naming the libmkkernel::MkErrorS::text and changing the libmkkernel::MkErrorS::code to libmkkernel::MK_ERROR.

[static] MkErrorC::PanicC(const MkObjectC* errobj, MK_STRN callfunc, MK_INT errnum, MK_STRN message)

TOP

do a panic with string as argument … → API: ccmkkernel::MkErrorC::PanicC

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errobja managed object used to identify and format the error-message
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]errnumthe error number used as exit-code as well
messagethe string to be displayed
Attention
this function will never return

[static] MkErrorC::PanicV(const MkObjectC* errobj, MK_STRN callfunc, MK_INT errnum, MK_FST printfmt, ... )

TOP

do a panic with a vararg as argument … → API: ccmkkernel::MkErrorC::PanicV

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errobja managed object used to identify and format the error-message
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]errnumthe error number used as exit-code as well
[in]printfmtis a c-string used as printf like format string
Attention
this function will never return

[static] MkErrorC::PanicVL(const MkObjectC* errobj, MK_STRN callfunc, MK_INT errnum, MK_FST printfmt, va_list var_list)

TOP

do a panic with a vararg-list as argument … → API: ccmkkernel::MkErrorC::PanicVL

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errobja managed object used to identify and format the error-message
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]errnumthe error number used as exit-code as well
[in]printfmtis a c-string used as printf like format string
[in]var_lista variable argument list object
Attention
this function will never return

err.AppendC(MK_STRN message)

TOP

append the message to the libmkkernel::MkErrorS::text … → API: ccmkkernel::MkErrorC::AppendC

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]messagethe string to be displayed as message (append)

err.AppendV(MK_FST printfmt, ... )

TOP

append a vararg string to the MkErrorC … → API: ccmkkernel::MkErrorC::AppendV

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]printfmtis a c-string used as printf like format string

err.AppendVL(MK_FST printfmt, va_list var_list)

TOP

append a va_list string to the MkErrorC … → API: ccmkkernel::MkErrorC::AppendVL

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]printfmtis a c-string used as printf like format string
[in]var_lista variable argument list object

MkErrorC* err.NoRaise()

TOP

ignore the next return of libmkkernel::MK_ERROR and do not raise an target-language-exception … → API: ccmkkernel::MkErrorC::NoRaise

Many functions from the MkErrorXXX return an libmkkernel::MkErrorE to signal that an libmkkernel::MK_ERROR is set. The target-language react on this signal and raise an target-language-exception.
If this behaviour is not desired the ErrorNoRaise is used to suppress the next libmkkernel::MK_ERROR return.

This feature is used to avoid the target-language-exception after ErrorSetC etc.

This is usefull if:

  1. an error should be send by MqSendERROR later
  2. an error will be extended by using multiple ErrorAppendC etc later and than raised with ErrorRaise

Example from server.cc create and send an background-error message

      void BgError () {
	MqContextC *master = SlaveGetMaster();
	if (master != NULL) {
          auto err = master->ErrorDEFAULT()->NoRaise();
	  err->SetC (err->GetText(), "BGERROR", err->GetNum());
	  master->SendERROR();
	}
      }
Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
Returns
the input err with libmkkernel::MkErrorS::noRaise flag set

err.Raise()

TOP

convert an ccmkkernel error into an programming-language-error and raise afterwards. … → API: ccmkkernel::MkErrorC::Raise

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

err.SetC(MK_STRN message, MK_STRN callfunc = __builtin_FUNCTION(), MK_INT errnum = -1)

TOP

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

The message will be formatted into a ccmkkernel error-message.

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed) - err==NULL allowed
[in]messagethe string to be displayed as message
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]errnumthe error number used as exit-code as well
Attention
Use ErrorNoRaise to avoid raise an error.

err.SetV(MK_STRN callfunc, MK_INT errnum, MK_FST printfmt, ... )

TOP

set the libmkkernel::MkErrorS object using a format string argument list and raise an error … → API: ccmkkernel::MkErrorC::SetV

The string argument list will be formatted into a ccmkkernel error-message.

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]errnumthe error number used as exit-code as well
[in]printfmtis a c-string used as printf like format string
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
Use ErrorNoRaise to avoid raise an error.

err.SetVL(MK_STRN callfunc, MK_INT errnum, MK_FST printfmt, va_list var_list)

TOP

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

The var_list will be formatted into a ccmkkernel error-message.

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe libmkkernel::MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]errnumthe error number used as exit-code as well
[in]printfmtis a c-string used as printf like format string
[in]var_lista variable argument list object
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
Use ErrorNoRaise to avoid raise an error.

MkErrorC SIGNAL

C-API: MkErrorC_Signal_C_API - various functions to set and check a 'signal' on a MkErrorC

MK_BOOL err.IsEXIT()

TOP

check on APPLICATION-EXIT error … → API: ccmkkernel::MkErrorC::IsEXIT

The exit-error-object is made for two resons:

  1. The error is set by ErrorSetEXIT to signal end-of-application.
  2. The error is raised by a function to signal a fatal-error which require an application-exit.
    The only source of this kind of fatal-error is a link-target-abnormal-exit caused by a server/network crash.

The link-target-abnormal-exit can only occur for functions that perform a network-request, such as:

  • MqLinkCreate, MqLinkCreateChild, MqLinkConnect, MqSendEND, MqSendEND_AND_WAIT or MqProcessEvent

The aim of this function is to react to an exit-error-object and is used to ignore the error with an ErrorReset and then later to re-establish a connection with a MqLinkConnect.

  • Read more from the: example//Filter4.cc example

Example "C": catch and ignore an EXIT return-code

if (MkErrorCheckI (MqSendEND_AND_WAIT (ctx, "TOKS", MK_TIMEOUT_USER))) {
}
#define MkErrorIsEXIT_0E()
#define MkErrorReset_1X(x)
#define MkErrorCheckI(err)

MK_BOOL err.IsSOCKET()

TOP

check on SOCKET-DOWN error … → API: ccmkkernel::MkErrorC::IsSOCKET

err.SetCONTINUE()

TOP

signal end of processing in an MqIEvent callback … → API: ccmkkernel::MkErrorC::SetCONTINUE

err.SetCode(MkErrorE code)

TOP

set the libmkkernel::MkErrorS::code value … → API: ccmkkernel::MkErrorC::SetCode

err.SetEXIT(MK_STRN callfunc = __builtin_FUNCTION())

TOP

finish the current callback, return to toplevel and MqExit the application … → API: ccmkkernel::MkErrorC::SetEXIT

To exit a application in a callback is a difficult task because the code is in-duty. To achieve this goal a special exit-error-object is created and reported to the toplevel. If a transaction is ongoing the MqSendRETURN is not called and thus the transaction is not finished. The calling application is informed later by a socket-down event. This only works for a parent-context. An exit in a child-context is ignored.

Example: raise an EXIT-exception in an ruby-service:

def EXIT
MkErrorC.DEFAULT().SetEXIT()
end

err.SetSOCKET(MK_STRN detail = "UNKNOWN", MK_STRN callfunc = __builtin_FUNCTION())

TOP

create SOCKET-DOWN error … → API: ccmkkernel::MkErrorC::SetSOCKET

MkErrorC SYSTEM

C-API: MkErrorC_System_C_API - various functions to reaise 'System' messagen on MkErrorC

[static] MkErrorC* MkErrorC::DEFAULT(const MkObjectC* fmtobj = NULL)

TOP

system-error - this is always the error in duty … → API: ccmkkernel::MkErrorC::DEFAULT

Set the libmkkernel::MkErrorS::format_of_error attribute to fmtobj or NULL. The next error-massage 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 libmkkernel::MkRuntimeS->cid ("context-in-duty") or simply as "DEFAULT" if cid == NULL.

Parameters
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
Returns
the default-error with libmkkernel::MkErrorS::format_of_error attribute set
See also
ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, ErrorPANIC

[static] MkErrorC* MkErrorC::IGNORE()

TOP

system-error - do not store the error in an MkErrorC and ignore the error … → API: ccmkkernel::MkErrorC::IGNORE

There are two functions to suppress an error: [static] MkErrorC* MkErrorC::IGNORE() and MkErrorC* err.NoRaise().

The [static] MkErrorC* MkErrorC::IGNORE() set the libmkkernel::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.

The MkErrorC* err.NoRaise() set the libmkkernel::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 err.Raise().

Returns
the default-error with libmkkernel::MkErrorS::format_of_error attribute set
See also
ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, ErrorPANIC

[static] MkErrorC* MkErrorC::PRINT()

TOP

system-error - print the error to the MkLogFileC … → API: ccmkkernel::MkErrorC::PRINT

Set the libmkkernel::MkErrorS::format_of_error attribute to PRINT. The next error-massage will be formated as usual and than be reported using LogVL. The default-error will not be modified.

Returns
the default-error with libmkkernel::MkErrorS::format_of_error attribute set
See also
ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, ErrorPANIC

MkErrorC TOR

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

[static] MkErrorC* MkErrorC::FromHandle(MK_LONG exporthdl)

TOP

Import-Slot - returns a obj from a former exported handle → API: ccmkkernel::MkErrorC::FromHandle

Parameters
[in]exporthdlhandle former exported with ObjectToHandle
Returns
the required handle or NULL if handle is invalid

[destructor] err.Delete()

TOP

Destructor - delete a libmkkernel::MkErrorS object … → API: libmkkernel::MkErrorDelete_RT

There are two different ways to delete an instance:

ObjectDisposeto 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 SelfDeleteForce
See also
BufferDup ObjectDelete

[constructor] srce.Dup()

TOP

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

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

Returns
The newly created MkErrorC instance, the instance is owned by the caller
See also
ObjDup ErrorDelete

MkLogFileC

MkLogFileC INTROSPECTION

Instancesget head-instance from linked-list of libmkkernel::MkLogFileS type …
Nextget next instance from linked-list of libmkkernel::MkLogFileS type
Prev

get previous instance from linked-list of libmkkernel::MkLogFileS type

MkLogFileC TOR

FromHandleImport-Slot - returns a obj from a former exported handle
Openopen the log-file in append mode …
Close

Destructor - delete a MkLogFileC instance …

MkLogFileC WRITE

GetFileget the log-file
WriteCwrite to log-file
WriteVwrite to log-file
WriteVL

write to log-file

MkLogFileC DETAIL

C-API: MkLogFileC_C_API - The MkLogFileC object 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.

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 INTROSPECTION

C-API: MkLogFileC_Introspection_C_API - Get information from the libmkkernel::MkTypeS.

Get information about all instances created by class

Get information about all instances created by class

The Introspection API is used to get information about the details of the instance and type implementation. Only the connection between type and instance is currently implemented.

Three methods are used to create an iteration over all avaialable instances of a type.

  • Every class has a Linked-List of all instances created starting from last to first.
  • The Introspection support always 3 Functions per class: Instance (static), Next and Prev
  • The Instance (example: [static] MkBufferC* MkBufferC::Instances())
    • return the last-instance created or NULL if no instance was created.
  • The Next (example: MkBufferC* buf.Next())
    • return the next-instance for a given-instance or NULL if the given-instance is the last-instance.
  • The Prev (example: MkBufferC* buf.Prev())
    • return the previous-instance for a given-instance or NULL if the given-instance is the first-instance.

Example: a simple loop over all instances of class MkBufferC (language C++)

for (auto buf = MkBufferC::Instances(); buf != NULL; buf = buf->Next()) {
SendC(buf->ToString());
}

[static] MkLogFileC* MkLogFileC::Instances()

TOP

get head-instance from linked-list of libmkkernel::MkLogFileS type … → API: ccmkkernel::MkLogFileC::Instances

The head-instance is the last instance created.

MkLogFileC* lfl.Next()

TOP

get next instance from linked-list of libmkkernel::MkLogFileS type → API: ccmkkernel::MkLogFileC::Next

MkLogFileC* lfl.Prev()

TOP

get previous instance from linked-list of libmkkernel::MkLogFileS type → API: ccmkkernel::MkLogFileC::Prev

MkLogFileC TOR

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

[static] MkLogFileC* MkLogFileC::FromHandle(MK_LONG exporthdl)

TOP

Import-Slot - returns a obj from a former exported handle → API: ccmkkernel::MkLogFileC::FromHandle

Parameters
[in]exporthdlhandle former exported with ObjectToHandle
Returns
the required handle or NULL if handle is invalid

[constructor] MkLogFileC::Open(MkObjectC* errobj, MK_STRN file)

TOP

open the log-file in append mode … → API: ccmkkernel::MkLogFileC::Open

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

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errobja managed object used to identify and format the error-message
[in]filethe filename to open
[out]lfh_outreturns
Returns
The newly created MkLogFileC instance, the instance is owned by the caller
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR
Attention
on error the lfh_out is set to NULL

[destructor] lfh.Close()

TOP

Destructor - delete a MkLogFileC instance … → API: libmkkernel::MkLogFileClose_RT

There are two different ways to delete an instance:

ObjectDisposeto 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 SelfDeleteForce
See also
LogFileOpen

MkLogFileC WRITE

C-API: MkLogFileC_Write_C_API - various functions to 'write' into a MkLogFileC

MK_STRN lfl.GetFile()

TOP

get the log-file … → API: ccmkkernel::MkLogFileC::GetFile

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]lflthe libmkkernel::MkLogFileS instance to work on
[out]file_outthe log-file to return
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

lfl.WriteC(MK_STRN text)

TOP

write to log-file … → API: ccmkkernel::MkLogFileC::WriteC

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]lflthe libmkkernel::MkLogFileS instance to work on
[in]textthe text to write
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

lfl.WriteV(MK_FST printfmt, ... )

TOP

write to log-file … → API: ccmkkernel::MkLogFileC::WriteV

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]lflthe libmkkernel::MkLogFileS instance to work on
[in]printfmtis a c-string used as printf like format string
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

lfl.WriteVL(MK_FST printfmt, va_list var_list)

TOP

write to log-file … → API: ccmkkernel::MkLogFileC::WriteVL

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]lflthe libmkkernel::MkLogFileS instance to work on
[in]printfmtis a c-string used as printf like format string
[in]var_lista variable argument list object
Returns
set the MkErrorC to the status libmkkernel::MK_OK, libmkkernel::MK_CONTINUE or libmkkernel::MK_ERROR

MkRuntimeC

MkRuntimeC CONFIG

Debuglog the MkRuntimeC
GetDebugget the libmkkernel::MkRuntimeS::debug value …
GetIsSilentget the libmkkernel::MkRuntimeS::isSilent value …
GetLogfileget the libmkkernel::MkRuntimeS::logfile value …
SetDebugset the libmkkernel::MkRuntimeS::debug value …
SetIsSilentset the libmkkernel::MkRuntimeS::isSilent value …
SetLogfile

set the libmkkernel::MkRuntimeS::logfile value and cleanup old value …

MkRuntimeC DETAIL

C-API: MkRuntimeC_C_API - The MkRuntimeC class known as mkrt or runtime is the main ccmkkernel application environment …

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

The runtime provide the following features:

  • the default-error -> MkErrorC
  • the runtime local storage (RLS) for various internal features
  • application wide configuration data like debug logfile or silent

To access the libmkkernel::MkRuntimeRLS in C or C++ the MkRuntimeC_Interface_C_API is used.

MkRuntimeC CONFIG

C-API: MkRuntimeC_Config_C_API - only C - various functions to configure the MkRuntimeC

The libmkkernel::MkRuntimeRLS-configuration belongs to a single libmkkernel::MkRuntimeRLS. In a threadable application, each thread has its own libmkkernel::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] MkRuntimeC::Debug(const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_INT lvl = 0)

TOP

log the MkRuntimeC … → API: ccmkkernel::MkRuntimeC::Debug

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]fmtobjmanaged object used to format the log-message (default=NULL = use default format)
[in]debugthe debug level from libmkkernel::MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)
See also
MkRuntimeC

[static] MK_INT MkRuntimeC::GetDebug()

TOP

get the libmkkernel::MkRuntimeS::debug value … → API: ccmkkernel::MkRuntimeC::GetDebug

[static] MK_BOOL MkRuntimeC::GetIsSilent()

TOP

get the libmkkernel::MkRuntimeS::isSilent value … → API: ccmkkernel::MkRuntimeC::GetIsSilent

[static] MK_STRN MkRuntimeC::GetLogfile()

TOP

get the libmkkernel::MkRuntimeS::logfile value … → API: ccmkkernel::MkRuntimeC::GetLogfile

Attention
the string is owned by ccmkkernel -> do not free !!

[static] MkRuntimeC::SetDebug(MK_INT dbg)

TOP

set the libmkkernel::MkRuntimeS::debug value … → API: ccmkkernel::MkRuntimeC::SetDebug

[static] MkRuntimeC::SetIsSilent(MK_BOOL silent)

TOP

set the libmkkernel::MkRuntimeS::isSilent value … → API: ccmkkernel::MkRuntimeC::SetIsSilent

[static] MkRuntimeC::SetLogfile(MK_STRN logfile)

TOP

set the libmkkernel::MkRuntimeS::logfile value and cleanup old value … → API: ccmkkernel::MkRuntimeC::SetLogfile

Parameters
[in]mkrtthe libmkkernel::MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]logfilefilename, "stdout" or "stderr", default = "stderr" for NULL or ""

BINARY OBJECT

No special binary-object is used. All binary-data is available as CC MK_BINN.


EXAMPLES

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

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

SEE ALSO

libmkkernel, ccmkkernel, csmkkernel, javamkkernel, gomkkernel, pymkkernel, rbmkkernel, tclmkkernel, perlmkkernel, phpmkkernel

KEYWORDS

C++, unix, socket, message, msgque