atlmkkernel

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

SYNOPSIS

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

• package require atlmkkernel 

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

object	description
MkKernel	the namespace with all atlmkkernel specific definitions
MkKernel::Attribute	the interface to access the package specific attribute
MkClassC::Attribute	the interface to access the class specific attribute
MkClassC::Attribute $Instance	the interface to access the instance specific attribute

To access all features without MkKernel prefix use:

• namespace path [list MkKernel ClassC ...]
    → The ATL is 'namespace-based' and TCL does not support a 'namespace-import' into an other namespace.
    → By default the PACKAGE '::MkKernel' and the '::ClassC' is defined in the GLOBAL namespace.
    → By default the ATTRIBUTE is always reachable by '::MkKernel::attribute' and '::ClassC::attribute'. 

Using the atlmkkernel package ...

ATL package libraries

libatlmkkernel.so

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

libatlmkkernel.la

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

> man n env

To access the atlmkkernel package the environment variable TCLLIBPATH have to include the directory.

TCLLIBPATH
      If set, then it must contain a valid Tcl list giving directories to search during auto-load operations.
      Directories must be specified in Tcl format, using “/” as the path separator, regardless of platform.  
      This variable is only used when initializing the auto_path variable.

> man n pkg_create

::pkg::create is a utility procedure that is part of the standard Tcl library.
It is used to create an appropriate `package ifneeded` command for a given package specification.
It can be used to construct a `pkgIndex.tcl` file for use with the package mechanism.

The syntax of the pkgIndex.tcl file is simple

package ifneeded NAME 9.0 [list load [file join $dir libNAME.so]]

> namespace path ?namespaceList?

Returns the command resolution path of the current namespace. If namespaceList is specified as a list of named namespaces, the current namespace's command resolution path is set to those namespaces and returns the empty list. The default command resolution path is always empty.

---

TABLE OF CONTENTS

BASICS

Philosophy , Package , ManagedObject , PrimitiveTypes , StorageManagement ,

CLASS

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

MISC

BinaryObject, Examples

INTRODUCTION

C-API: MK_C_API - The LibMkKernel API …

Unlocking the Power of C Across All Languages: Discover theKernel

The world of software development often faces a fundamental challenge: harnessing the unparalleled performance and vast ecosystem of C libraries while building applications in modern, higher-level programming languages. Traditionally, this requires creating complex, language-specific bindings for each library and each target language.

But what if there was a way to bridge this gap seamlessly, enabling you to

Write Once → Run Everywhere ?

Enter theKernel, a revolutionary infrastructure designed to provide a programming-language-independent-interface between a C librarie and a multitude of Target-Programming-Language (TPL). At its core lies the Programming-Language-Micro-Kernel (PLMK), implemented primarily by the C library atlmkkernel. This isn't just another binding generator; it's a comprehensive system that defines an object-layer and manages the interaction between your robust C code and diverse language environments.

The strategic approach is described as taking

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

The magic happens through a sophisticated object-interface and an api-layer automatically generated by the meta-code-compiler (META-COMPILER).

PROGRAMMING

This structure is clearly defined by separating concerns into three distinct programming layers:

1. the library-layer (atlmkkernel),
2. the tool-layer (theCompiler and build tools),
3. the target-layer (the API seen by the Target-Programming-Language (TPL) programmer).

library-layer

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

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

tool-layer

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

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

target-layer

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

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

Target

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

PACKAGE

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

The atlmkkernel package is loaded with:

‍

package require atlmkkernel 

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

The atlmkkernel package add the following public classes into MkObjectC_C_API :

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

The atlmkkernel package add the following public types into MkObjectC_C_API :

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

MANAGED OBJECT

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

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

Integration

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

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

Managed-Object

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

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

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

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

See also

For the full documentation read: Managed-Object

PRIMITIVE TYPE

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

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

The following native-type identifier are available:

TT	T	native	comment
BOL	O	bool	1 byte boolean value using true or false
I8	Y	int8	1 byte signed character
I16	S	int16	2 byte signed short
I32	I	int32	4 byte signed integer
I64	W	int64	8 byte signed long long integer
FLT	F	float	4 byte float
DBL	D	double	8 byte double
BIN	B	binary	unsigned char array used for binary data
STR	C	string	string data using a \0 at the end

The following composee identifier's are available:

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

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

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

POINTER TYPE

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

For native type support read: MkKernel_PrimitiveType_C_API

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

The following pointer-type identifier is available in MkBufferS:

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

STORAGE MANAGEMENT

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

Storage management is used in atlmkkernel to provide temporary storage. It is a common design pattern that atlmkkernel 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 atlmkkernel distinguishes three different storage sources:

Context-Local-Storage (CLS)

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

Funktion-Local-Storage (FLS)

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

Runtime-Local-Storage (RLS)

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

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

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

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

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

Example from server.atl → ReadBFL overwrite previous ReadBFL

  proc Ot_BFL2 { myNs } {
    set tmp1  [ReadBFL $myNs]                 ; # "tmp1" is now a reference to the FLS storage of "ReadBFL"
    set tmp2  [ReadBFL $myNs]                 ; # ERROR: the "tmp2" is using a SHARED reference with "tmp1"
    Send $myNs "R" "LL" $tmp1 $tmp2           ; # ERROR: "$tmp1" and "$tmp2" are the SAME values
  }

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

  proc pBFL3 { myNs } {
    set tmp2  [ReadBFL $myNs]                 ; # ERROR: the "tmp2" is using a SHARED reference with "tmp1"
  }
  proc Ot_BFL3 { myNs } {
    set tmp1  [ReadBFL $myNs]                 ; # "tmp1" is now a reference to the FLS storage of "ReadBFL"
    Send $myNs "C" pBFL3 {ECOL:[III]} 4 5 6   ; # ATTENTION: callback "pBFL3" using "ReadBFL"
    ProcessEvent $myNs MQ_WAIT_OWN            ; # ERROR: enter event-loop, callback "pBFL3" is called
    Send $myNs "R" "L" $tmp1                  ; # ERROR: "$tmp1" has now the value from "$tmp2"
  }

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

  proc Ot_BFL4 { myNs } {
    set tmp1  [ReadBFL $myNs]                 ; # "tmp1" is now a reference to the FLS storage of "ReadBFL"
    set glb1  [MkBufferListC::Dup $tmp1]      ; # OK: "glb1" is now a UNSHARED reference to the global memory
    set tmp2  [ReadBFL $myNs]                 ; # "tmp2" is now a reference to the FLS storage of "ReadBFL"
    Send $myNs "R" "LL" $glb1 $tmp2           ; # OK: "glb1" (alias tmp1) and "tmp2" are separate references
    myooX::DestroyN $glb1                     ; # without "garbage-collection" the global memory must be released
  }

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

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

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

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

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

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

Attention

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

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

  proc Ot_BUST { myNs } {
    set bus [MkBufferStreamC::CreateTLS "perfserver-BUST" ]
    while {[ReadItemExists $myNs]} {
      MkBufferStreamC::WriteBUF $bus [ReadBUF $myNs]
    }
    MkBufferStreamC::PosToStart $bus
    SendSTART $myNs
    while {[MkBufferStreamC::ReadItemExists $bus]} {
      SendBUF $myNs [MkBufferStreamC::ReadBUF $bus]
    }
    SendRETURN $myNs
  }

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

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

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

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

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

---

MkKernel PACKAGE

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

MkKernel DETAIL

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

The atlmkkernel package is loaded with:

‍

package require atlmkkernel 

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

The atlmkkernel package add the following public classes into MkObjectC_C_API :

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

The atlmkkernel package add the following public types into MkObjectC_C_API :

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

MkKernel SETUP

NAVI: top, up

		Cleanup	cleanup atlmkkernel internal memory …
		Setup	setup atlmkkernel internal memory …

MkKernel SETUP DETAILS

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

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

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

• In a static build the shared library constructor/destructor is NOT called
• In a shared build the order of library loading is target-language-specific
• Every executable who uses a meta-code-library (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 atlmkkernel 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 atlmkkernel library startup functions

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

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

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

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

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

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

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

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

(static) MkKernel::Cleanup

top cleanup atlmkkernel internal memory … → API: atlmkkernel_MkKernel_Cleanup

/

/noop [MkCleanup] Cleanup will only be recognized once and will be ignored if not called in the same thread as Setup. After a call to Setup the call to MkCleanup is possible again.

1. By default, the public Cleanup with the gcc: __attribute__ ((cleanup(XXX))) is called when unloading the library.
2. The public Cleanup is only a placeholder and should not be used, the internal Cleanup is always called, even if the public Cleanup is not called.

Note

during cleanup objects will be deleted too -> the language interpreter have to be active /noop [MkCleanup]

(static) MkKernel::Setup

top setup atlmkkernel internal memory … → API: atlmkkernel_MkKernel_Setup

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

1. By default, the public Setup with the gcc: __attribute__ ((constructor(XXX))) is called when loading the library.
2. If the Target-Programming-Language (TPL) supports late loading of a shared library with dlopen and additionally uses threads, a manual call to Setup very early at startup is required to enforce the correct order of type declarations.

MkKernel ENUM

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

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

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

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

enum MkErrorE

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

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

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

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

top return the MkErrorE from integer … → API: atlmkkernel_MkKernel_ErrorE_FromInt

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

top return the MkErrorE as integer … → API: atlmkkernel_MkKernel_ErrorE_ToInt

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

top return the MkErrorE as string … → API: atlmkkernel_MkKernel_ErrorE_ToString

enum MkIdSE

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

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

top return the MkIdSE from integer … → API: atlmkkernel_MkKernel_IdSE_FromInt

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

top return the MkIdSE as integer … → API: atlmkkernel_MkKernel_IdSE_ToInt

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

top return the MkIdSE as string … → API: atlmkkernel_MkKernel_IdSE_ToString

enum MkTimeoutE

top Predefined Timeout values … → API: atlmkkernel_Get_MkTimeoutE_FromObj

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

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

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

top return the MkTimeoutE from integer … → API: atlmkkernel_MkKernel_TimeoutE_FromInt

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

top return the MkTimeoutE as integer … → API: atlmkkernel_MkKernel_TimeoutE_ToInt

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

top return the MkTimeoutE as string … → API: atlmkkernel_MkKernel_TimeoutE_ToString

enum MkTypeE

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

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

See also

MkTypeE_ToString, MkTypeE_ToInt, MkTypeE_FromInt, BufferGetType2, BufferCastTo, BufferStreamReadGetNextType

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

top return the MkTypeE from integer … → API: atlmkkernel_MkKernel_TypeE_FromInt

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

top return the MkTypeE as integer … → API: atlmkkernel_MkKernel_TypeE_ToInt

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

top return the MkTypeE as string … → API: atlmkkernel_MkKernel_TypeE_ToString

---

MkObjectC

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

MkObjectC DETAIL

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

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

Integration

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

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

Managed-Object

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

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

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

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

See also

For the full documentation read: Managed-Object

MkObjectC CLASS

NAVI: top, up

MkObjectC CLASS EXPORT

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

MkObjectC CLASS INTROSPECTION

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

MkObjectC CLASS MISC

GetNull

Null-Slot - return a MkObjectC typed NULL instance …

MkObjectC CLASS DETAILS

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

MkObjectC CLASS EXPORT

MkObjectC - Export class functions …

(static) MkObjectC::HandleDeleteByNetHdl netHdl:MK_HDL

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

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

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MkObjectC::HandleDelete $netObj

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

bool [MkObjectC::HandleExists $obj]

top check if obj has already a handle defined… → API: atlmkkernel_MkObjectC_HandleExists

Parameters

[in]

obj

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

Returns

true or false

MK_HDL [MkObjectC::HandleGet $obj]

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

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

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

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

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

Parameters

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

Returns

the required export-hdl

MK_HDL [MkObjectC::HandleGetOfType $obj]

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

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

Parameters

[in]

obj

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

Returns

the required typeHdl

MK_HDL [MkObjectC::HandleGetOr0 $obj]

top return export-hdl or 0 in not created… → API: atlmkkernel_MkObjectC_HandleGetOr0

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

Parameters

[in]

obj

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

Returns

the required export-hdl

MkObjectC CLASS INTROSPECTION

MkObjectC - Introspection class functions …

(static) MkObjectC [MkObjectC::Instances]

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

The head-instance is the last instance created.

MkObjectC [MkObjectC::Next $obj]

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

MkObjectC [MkObjectC::Prev $obj]

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

MkObjectC CLASS MISC

MkObjectC - Misc class functions …

(static) MkObjectC [MkObjectC::GetNull]

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

MkObjectC TOR

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

(static) MkObjectC::DeleteCallbackCleanup ident:string

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

See also

MkObjectDeleteCallbackSetup

(static) MkObjectC::DeleteCallbackSetup ident:string ?callback:callable=NULL? ?filter:string="NULL"?

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

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

The ident identifies the callback

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

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

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

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

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

C-callback definition details:

Read more at MkObjectDeleteCallF

Parameters

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

See also

MkObjectDeleteCallbackCleanup

MkObjectDeleteCallbackSetup : callback signature

Read more at: Callback Signature List

MkObjectDeleteCallbackSetup : callback example

Read more at: Callback Signature List

(destructor) MkObjectC::Delete $obj

top Delete-Slot - delete an instance. → API: atlmkkernel_MkObjectC_Delete

There are two different ways to delete an instance:

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

Attention

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

(destructor) MkObjectC::Dispose $obj

top Dispose-Slot - untie the connection between the Native-Atl-Instance and the atlmkkernel-Instance. → API: atlmkkernel_MkObjectC_Dispose

There are two different ways to delete an instance:

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

Attention

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

MkObjectC DBG

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

This functions are "helpers" to support the programmer.

(static) MkObjectC::DbgM message:string ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

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

MkObjectC::DbgDump $obj ?message:string="var"? ?callfunc:string="MK_NULL"?

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

Attention

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

MkObjectC::DbgL $fmtobj message:string ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

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

The marker is prefixed with object data from th fmtobj.

MkObjectC::DbgLogC $obj ?callfunc:string="MK_NULL"?

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

MkObjectC::DbgO $obj ?callfunc:string="MK_NULL"?

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

Parameters

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

This function can be overwritten in the target programming language.

MkObjectC::DbgSTACK $fmtobj ?skip:int32=0? ?num:int32=-1? ?callfunc:string="MK_NULL"?

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

MkObjectC LOG

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

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

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

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

possible values are:

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

Many logging functions have common parameters:

Parameters

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

MkObjectC::LogC $fmtobj message:string ?debug:int32=0? ?callfunc:string="MK_NULL"?

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

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

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

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

Parameters

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

MkObjectC::LogHEX $fmtobj callfunc:string data:binary

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

Parameters

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

MkObjectC::Log $obj ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

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

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

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

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

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

Example: logging of a buffer object in RUBY :

require "rbmkkernel"
include MkKernel

buf = MkBufferC.CreateSTR("Hallo World")

buf.Log()

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

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

Parameters

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

See also

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

MkObjectC::LogLong $obj ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

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

Parameters

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

See also

MkObjectC MkObjectC::Log $obj ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

MkObjectC::LogShort $obj ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

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

Parameters

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

See also

MkObjectC

MkObjectC::LogType $obj ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

top log the tyoe of the MkObjectS into the MkLogFileC (default: stderr) … → API: atlmkkernel_MkObjectC_LogType

Parameters

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

See also

MkObjectC MkObjectC::Log $obj ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

MkObjectC MISC

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

MkErrorC [MkObjectC::ErrorCatch $obj ?exception:errorCode=NULL? ?callfunc:string="MK_NULL"?]

top convert a programming-language-error into an atlmkkernel error … → API: atlmkkernel_MkObjectC_ErrorCatch

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

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

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

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

        SendSTART $cl
        try {
          ProxyItem $myNs $cl
          SendEND_AND_WAIT $cl "ECOI" 5
        } on error {} {
          set err [ErrorCatch $cl]
          SendI32 $myNs [MkErrorC::GetNum $err]
          SendSTR $myNs [MkErrorC::GetText $err]
          MkErrorC::Reset $err
        }

Note

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

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

Parameters

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

Returns

the ErrorDEFAULT initialized with exception value

See also

MkErrorC::Raise $err MkErrorC::Reset $err ?callfunc:string="MK_NULL"? ?callline:int32=-1? ?force:bool=false?

bool [MkObjectC::IsNull $obj]

top ckeck if the object is "MK_NULL" → API: atlmkkernel_MkObjectC_IsNull

MkErrorC [MkObjectC::ToError $obj]

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

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

Parameters

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

Returns

the error-object

Attention

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

string [MkObjectC::ToName $obj]

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

Parameters

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

Returns

the identification of the object as string

Attention

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

string [MkObjectC::ToNameOfClass $obj]

top Class-Slot - returns the Atl-Class-Name of the obj as string → API: atlmkkernel_MkObjectC_ToNameOfClass

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

ObjectToNameOfType	returns the name of the atlmkkernel type
ObjectToNameOfClass	returns the name of the Atl class

string [MkObjectC::ToNameOfType $obj]

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

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

ObjectToNameOfType	returns the name of the libmsgque type
ObjectToNameOfClass	returns the name of the Atl class

Parameters

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

Returns

the name of the object-type as a string

string [MkObjectC::ToString $inst]

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

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

See also

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

Parameters

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

Returns

the requested string or "MK_NULL" on error

Note

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

---

MkBufferC

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

MkBufferC DETAIL

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

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

MkBufferC CLASS

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

C-Kernel-Details

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

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

‍A MkBufferS never run out of storage.

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

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

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

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

‍MkBuffer64C, MkBuffer256C and MkBuffer1024C

See also

MkBufferListC, MkBufferStreamC

MkBufferC CTOR / DTOR

command	synonmym
(constructor,static) MkBufferC [MkBufferC::Create ?size:int32=0?]	myooX::NewN ::MkBufferC ?size:W=0?
(destructor) MkBufferC::Delete $buf	myooX::DestroyN $buf

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

  proc Ot_BUF2 { myNs } {
    SendSTART $myNs

    foreach i {1 2 3} {
      set buf [ReadBUF $myNs]
      SendSTR $myNs [MkBufferC::GetType1 $buf]
      SendBUF $myNs $buf
      myooX::DestroyN $buf
    }

    SendRETURN $myNs
  }

See also

BufferGetType1 BufferGetType2 BufferGetType3

MkBufferC CLASS

NAVI: top, up

MkBufferC CLASS EXPORT

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

MkBufferC CLASS INTROSPECTION

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

MkBufferC CLASS MISC

GetNull

Null-Slot - return a MkBufferC typed NULL instance …

MkBufferC CLASS DETAILS

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

MkBufferC CLASS EXPORT

MkBufferC - Export class functions …

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

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [MkBufferC::HandleGet $buf]

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

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

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

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

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

Parameters

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

Returns

the required export-hdl

MkBufferC CLASS INTROSPECTION

MkBufferC - Introspection class functions …

(static) MkBufferC [MkBufferC::Instances]

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

The head-instance is the last instance created.

MkBufferC [MkBufferC::Next $buf]

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

MkBufferC [MkBufferC::Prev $buf]

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

MkBufferC CLASS MISC

MkBufferC - Misc class functions …

(static) MkBufferC [MkBufferC::GetNull]

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

MkBufferC TOR

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

(constructor,static) MkBufferC [MkBufferC::Create ?size:int32=0?]

top Constructor - create a new MkBufferC with minimum size of internal storage … → API: atlmkkernel_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 MkBufferCreateTT function for every PRIMITIVE TYPE.

Parameters

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

Returns

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

See also

BufferDelete BufferDup MqReadBUF

(static) MkBufferC [MkBufferC::CreateTLS tlsName:string ?resetB:bool=true?]

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

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

Parameters

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

Returns

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

Note

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

Attention

for usage of the TLS-storage read more at StorageCreateTLS

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

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

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

Returns

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

Parameters

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

(constructor,static) MkBufferC [MkBufferC::Create64 ?size:int32=0?]

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

(constructor,static) MkBufferC [MkBufferC::Create256 ?size:int32=0?]

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

(constructor,static) MkBufferC [MkBufferC::Create1024 ?size:int32=0?]

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

(constructor,static) MkBufferC [MkBufferC::CTOR ?size:int32=0?]

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

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

There is a MkBufferCreateTT function for every PRIMITIVE TYPE.

Parameters

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

Returns

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

See also

BufferDelete BufferDup MqReadBUF

(destructor) MkBufferC::Delete $buf

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

There are two different ways to delete an instance:

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

Attention

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

See also

BufferCreate BufferDup MqReadBUF

(constructor) MkBufferC [MkBufferC::Dup $buf]

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

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

Parameters

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

Returns

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

See also

MkObjDup MkBufferDelete

(constructor) MkBufferC [MkBufferC::Merge $buf]

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

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

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

Parameters

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

Returns

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

Attention

The new instance have to be deleted with BufferDelete

See also

BufferDup BufferResetFull BufferDelete

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

top

The BufferCreateTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
(constructor,static)	MkBufferC	[MkBufferC::CreateI8 val:int8]	MkBufferCreateI8_RT
(constructor,static)	MkBufferC	[MkBufferC::CreateI16 val:int16]	MkBufferCreateI16_RT
(constructor,static)	MkBufferC	[MkBufferC::CreateI32 val:int32]	MkBufferCreateI32_RT
(constructor,static)	MkBufferC	[MkBufferC::CreateI64 val:int64]	MkBufferCreateI64_RT
(constructor,static)	MkBufferC	[MkBufferC::CreateSTR val:string]	MkBufferCreateSTR_RT
(constructor,static)	MkBufferC	[MkBufferC::CreateBIN val:binary]	MkBufferCreateBIN_RT
(constructor,static)	MkBufferC	[MkBufferC::CreateBOL val:bool]	MkBufferCreateBOL_RT
(constructor,static)	MkBufferC	[MkBufferC::CreateFLT val:float]	MkBufferCreateFLT_RT
(constructor,static)	MkBufferC	[MkBufferC::CreateDBL val:double]	MkBufferCreateDBL_RT

Constructor - create a new MkBufferC with an PRIMITIVE TYPE …

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

Returns

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

Parameters

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

MkBufferC SET

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

MkBufferC [MkBufferC::SetBinaryR $buf val:binary]

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

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

Returns

the MkBufferS object

Parameters

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

MkBufferC [MkBufferC::SetBUF $buf val:MkBufferC]

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

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

Returns

the MkBufferS object

Parameters

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

MkBufferC [MkBufferC::SetStringR $buf val:string]

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

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

Returns

the MkBufferS object

Parameters

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

[MkBufferC::SetTT $buf val:int8]

top

The BufferSetTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	MkBufferC	[MkBufferC::SetI8 $buf val:int8]	MkBufferSetI8_RT
	MkBufferC	[MkBufferC::SetI16 $buf val:int16]	MkBufferSetI16_RT
	MkBufferC	[MkBufferC::SetI32 $buf val:int32]	MkBufferSetI32_RT
	MkBufferC	[MkBufferC::SetI64 $buf val:int64]	MkBufferSetI64_RT
	MkBufferC	[MkBufferC::SetSTR $buf val:string]	MkBufferSetSTR_RT
	MkBufferC	[MkBufferC::SetBIN $buf val:binary]	MkBufferSetBIN_RT
	MkBufferC	[MkBufferC::SetBOL $buf val:bool]	MkBufferSetBOL_RT
	MkBufferC	[MkBufferC::SetFLT $buf val:float]	MkBufferSetFLT_RT
	MkBufferC	[MkBufferC::SetDBL $buf val:double]	MkBufferSetDBL_RT

Set the MkBufferC to the val …

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

Returns

the MkBufferS object

Parameters

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

MkBufferC GET

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

MkBufferListC [MkBufferC::GetBFL $buf ?val_inout:MkBufferListC=NULL?]

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

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

Parameters

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

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

Exceptions

MkExceptionC

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

MkBufferC [MkBufferC::GetBUF $buf]

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

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

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

Exceptions

MkExceptionC

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

Parameters

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

Attention

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

string [MkBufferC::GetStringR $buf]

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

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

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

Exceptions

MkExceptionC

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

Parameters

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

Attention

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

[MkBufferC::GetTT $buf]

top

The BufferGetTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	int8	[MkBufferC::GetI8 $buf]	MkBufferGetI8_RT
	int16	[MkBufferC::GetI16 $buf]	MkBufferGetI16_RT
	int32	[MkBufferC::GetI32 $buf]	MkBufferGetI32_RT
	int64	[MkBufferC::GetI64 $buf]	MkBufferGetI64_RT
	string	[MkBufferC::GetSTR $buf]	MkBufferGetSTR_RT
	binary	[MkBufferC::GetBIN $buf]	MkBufferGetBIN_RT
	bool	[MkBufferC::GetBOL $buf]	MkBufferGetBOL_RT
	float	[MkBufferC::GetFLT $buf]	MkBufferGetFLT_RT
	double	[MkBufferC::GetDBL $buf]	MkBufferGetDBL_RT

get a val_out from a MkBufferC …

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

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

Exceptions

MkExceptionC

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

Parameters

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

MkBufferC ACCESS

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

MkBufferC [MkBufferC::AppendC $buf val:string]

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

Parameters

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

Returns

the MkBufferC object with the new value

Example from server.atl → read and update a MkBufferC

        # START - ReadBUF - Example, read a buffer-object and append a string
        set buf [ReadBUF $myNs]
        MkBufferC::AppendC $buf "- a really log text to overwrite the already allocated space"
        SendBUF $myNs $buf
        set i   [ReadI32 $myNs]
        SendI32 $myNs [expr {$i+1}]
        myooX::DestroyN $buf

MkBufferC [MkBufferC::AppendStringR $buf val:string]

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

Parameters

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

Returns

the MkBufferC object with the new value

Example from server.atl → read and update a MkBufferC

        # START - ReadBUF - Example, read a buffer-object and append a string
        set buf [ReadBUF $myNs]
        MkBufferC::AppendC $buf "- a really log text to overwrite the already allocated space"
        SendBUF $myNs $buf
        set i   [ReadI32 $myNs]
        SendI32 $myNs [expr {$i+1}]
        myooX::DestroyN $buf

int32 [MkBufferC::Pop $buf val:string]

top delete str from the MkBufferC … → API: atlmkkernel_MkBufferC_Pop

Parameters

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

Returns

the size of the string removed from the MkBuffer64S object

Attention

MkBufferC have to be of type MK_STRT

int32 [MkBufferC::Push $buf val:string]

top add str to the MkBufferC … → API: atlmkkernel_MkBufferC_Push

Parameters

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

Returns

the size of the string appended to the MkBuffer64S object

Attention

MkBufferC have to be of type MK_STRT

obj [MkBufferC::ToObject $buf]

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

MkBufferC INFO

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

string[1] [MkBufferC::GetType1 $buf]

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

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

MkTypeE [MkBufferC::GetType2 $buf]

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

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

string [MkBufferC::GetType3 $buf]

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

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

bool [MkBufferC::IsLocal $buf]

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

Parameters

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

Returns

a boolean value… yes or no

MkBufferC::Log $buf ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

top log the MkBufferC … → API: atlmkkernel_MkObjectC_Log

Parameters

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

See also

MkBufferC

MkBufferC::LogS $buf ?varname:string="buf"? ?fmtobj:MkObjectC=NULL? ?callfunc:string="MK_NULL"?

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

Parameters

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

MkBufferC MISC

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

MkBufferC::CastTo $buf typ:MkTypeE

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

Parameters

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

Exceptions

MkExceptionC

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

int32 [MkBufferC::Cmp $buf1 buf2:MkBufferC]

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

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

Parameters

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

Returns

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

MkBufferC [MkBufferC::Copy $buf srce:MkBufferC]

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

Parameters

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

Returns

the dest object

MkBufferC [MkBufferC::Reset $buf]

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

Parameters

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

See also

MkBufferC::ResetFull $buf

MkBufferC::ResetFull $buf

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

In addition to MkBufferC [MkBufferC::Reset $buf] the allocated storage is freed and reset to ILS

Parameters

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

See also

MkBufferC [MkBufferC::Reset $buf]

MkBufferC [MkBufferC::SizeAdd $buf size:int32]

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

Parameters

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

Returns

the input buf

MkBufferC [MkBufferC::SizeNew $buf size:int32]

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

Returns

the input buf

Parameters

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

MkBufferC [MkBufferC::Temp $buf]

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

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

Parameters

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

Returns

the temporary buffer-object

Attention

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

string [MkBufferC::ToString $inst]

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

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

See also

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

Parameters

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

Returns

the requested string or "MK_NULL" on error

Note

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

---

MkBufferStreamC

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

MkBufferStreamC DETAIL

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

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

‍See also: MkBufferC, MkBufferListC

C-Kernel-Details

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

private-parent-class mean:

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

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

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

The MkBufferStreamS inherits the following features from MkBufferS:

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

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

‍MkBufferStream16384S, MkBufferStream256S, MkBufferStream64S and MkBufferStream1024S

See also

MkBufferC, MkBufferListC

MkBufferStreamC CLASS

NAVI: top, up

MkBufferStreamC CLASS EXPORT

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

MkBufferStreamC CLASS INTROSPECTION

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

MkBufferStreamC CLASS MISC

GetNull

Null-Slot - return a MkBufferStreamC typed NULL instance …

MkBufferStreamC CLASS DETAILS

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

MkBufferStreamC CLASS EXPORT

MkBufferStreamC - Export class functions …

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

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [MkBufferStreamC::HandleGet $bus]

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

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

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

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

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

Parameters

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

Returns

the required export-hdl

MkBufferStreamC CLASS INTROSPECTION

MkBufferStreamC - Introspection class functions …

(static) MkBufferStreamC [MkBufferStreamC::Instances]

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

The head-instance is the last instance created.

MkBufferStreamC [MkBufferStreamC::Next $bus]

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

MkBufferStreamC [MkBufferStreamC::Prev $bus]

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

MkBufferStreamC CLASS MISC

MkBufferStreamC - Misc class functions …

(static) MkBufferStreamC [MkBufferStreamC::GetNull]

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

MkBufferStreamC TOR

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

(constructor,static) MkBufferStreamC [MkBufferStreamC::Create ?size:int32=0?]

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

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

Parameters

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

Returns

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

(constructor,static) MkBufferStreamC [MkBufferStreamC::Create64 ?size:int32=0?]

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

(constructor,static) MkBufferStreamC [MkBufferStreamC::Create256 ?size:int32=0?]

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

(constructor,static) MkBufferStreamC [MkBufferStreamC::Create1024 ?size:int32=0?]

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

(constructor,static) MkBufferStreamC [MkBufferStreamC::Create16384 ?size:int32=0?]

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

(static) MkBufferStreamC [MkBufferStreamC::CreateTLS tlsName:string ?resetB:bool=true?]

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

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

Example from perfserver.atl → performance test with TLS storage

  proc Ot_BUST { myNs } {
    set bus [MkBufferStreamC::CreateTLS "perfserver-BUST" ]
    while {[ReadItemExists $myNs]} {
      MkBufferStreamC::WriteBUF $bus [ReadBUF $myNs]
    }
    MkBufferStreamC::PosToStart $bus
    SendSTART $myNs
    while {[MkBufferStreamC::ReadItemExists $bus]} {
      SendBUF $myNs [MkBufferStreamC::ReadBUF $bus]
    }
    SendRETURN $myNs
  }

Parameters

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

Returns

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

Note

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

Attention

for usage of the TLS-storage read more at StorageCreateTLS

(constructor,static) MkBufferStreamC [MkBufferStreamC::CTOR ?size:int32=0?]

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

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

Parameters

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

Returns

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

(destructor) MkBufferStreamC::Delete $bus

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

There are two different ways to delete an instance:

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

Attention

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

See also

BufferStreamCreate BufferStreamDup

(constructor) MkBufferStreamC [MkBufferStreamC::Dup $src]

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

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

Returns

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

See also

MkObjDup MkBufferStreamDelete

(constructor) MkBufferStreamC [MkBufferStreamC::Merge $bus]

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

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

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

Parameters

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

Returns

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

Attention

The new instance have to be deleted with BufferStreamDelete

See also

BufferStreamDup BufferStreamResetFull BufferStreamDelete

MkBufferStreamC READ

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

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

MkBufferListC [MkBufferStreamC::ReadALL $bus ?val_inout:MkBufferListC=NULL?]

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

Parameters

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

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

Exceptions

MkExceptionC

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

See also

BufferStreamReadBFL

MkBufferListC [MkBufferStreamC::ReadBFL $bus]

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

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

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

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

Parameters

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

Exceptions

MkExceptionC

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

See also

BufferStreamReadALL BufferStreamWriteBFL

Attention

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

MkBufferC [MkBufferStreamC::ReadBUF $bus]

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

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

Precondition

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

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

To reset the current-access-position to the start use MkBufferStreamC::PosToStart $bus.

Exceptions

MkExceptionC

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

Parameters

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

MkTypeE [MkBufferStreamC::ReadGetNextType $bus]

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

Parameters

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

Returns

the type

int32 [MkBufferStreamC::ReadGetNumItems $bus]

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

Parameters

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

Returns

the number of items as integer

bool [MkBufferStreamC::ReadItemExists $bus]

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

Parameters

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

Returns

boolean, true or false

MkBufferStreamC::ReadL_END $bus

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

MkBufferStreamC::ReadL_START $bus ?buf:MkBufferC=NULL?

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

Parameters

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

Exceptions

MkExceptionC

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

long [MkBufferStreamC::ReadLONG $bus]

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

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

this api-function is NOT portable

See also

MkBufferStreamC::WriteLONG $bus val:long

MkBufferStreamC::ReadUndo $bus

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

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

Parameters

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

Exceptions

MkExceptionC

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

[MkBufferStreamC::ReadTT $bus]

top

The BufferStreamReadTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	int8	[MkBufferStreamC::ReadI8 $bus]	MkBufferStreamReadI8_RT
	int32	[MkBufferStreamC::ReadI32 $bus]	MkBufferStreamReadI32_RT
	int64	[MkBufferStreamC::ReadI64 $bus]	MkBufferStreamReadI64_RT
	string	[MkBufferStreamC::ReadSTR $bus]	MkBufferStreamReadSTR_RT
	binary	[MkBufferStreamC::ReadBIN $bus]	MkBufferStreamReadBIN_RT
	bool	[MkBufferStreamC::ReadBOL $bus]	MkBufferStreamReadBOL_RT
	float	[MkBufferStreamC::ReadFLT $bus]	MkBufferStreamReadFLT_RT
	double	[MkBufferStreamC::ReadDBL $bus]	MkBufferStreamReadDBL_RT

read a val_out from the MkBufferStreamC …

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

Precondition

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

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

To reset the current-access-position to the start use MkBufferStreamC::PosToStart $bus.

Exceptions

MkExceptionC

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

Parameters

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

MkBufferStreamC WRITE

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

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

MkBufferStreamC::WriteBFL $bus bfl:MkBufferListC

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

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

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

Parameters

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

Exceptions

MkExceptionC

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

See also

BufferStreamWriteL_FLAT BufferStreamReadBFL

MkBufferStreamC::WriteBUF $bus val:MkBufferC

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

After every write the current-access-position is incremented by one, use MkBufferStreamC [MkBufferStreamC::Reset $bus] to reset.

Parameters

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

Exceptions

MkExceptionC

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

MkBufferStreamC::WriteBUS_FLAT $bus add:MkBufferStreamC

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

The add is appended to bus

Parameters

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

Exceptions

MkExceptionC

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

MkBufferStreamC::WriteHDL $bus val:int32

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

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

The handle support the following API:

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

MkBufferStreamC::WriteL_END $bus

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

MkBufferStreamC::WriteL_FLAT $bus bfl:MkBufferListC

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

A MkBufferListC can be written into a MkBufferStreamC using:

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

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

Parameters

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

Exceptions

MkExceptionC

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

See also

MkBufferStreamReadBFL

MkBufferStreamC::WriteL_START $bus

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

MkBufferStreamC::WriteLONG $bus val:long

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

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

this api-function is NOT portable

See also

long [MkBufferStreamC::ReadLONG $bus]

MkBufferStreamC::WriteTT $bus val:int8

top

The BufferStreamWriteTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
		MkBufferStreamC::WriteI8 $bus val:int8	MkBufferStreamWriteI8_RT
		MkBufferStreamC::WriteI32 $bus val:int32	MkBufferStreamWriteI32_RT
		MkBufferStreamC::WriteI64 $bus val:int64	MkBufferStreamWriteI64_RT
		MkBufferStreamC::WriteSTR $bus val:string ?len:int32=-1?	MkBufferStreamWriteSTR_RT
		MkBufferStreamC::WriteBIN $bus val:binary	MkBufferStreamWriteBIN_RT
		MkBufferStreamC::WriteBOL $bus val:bool	MkBufferStreamWriteBOL_RT
		MkBufferStreamC::WriteFLT $bus val:float	MkBufferStreamWriteFLT_RT
		MkBufferStreamC::WriteDBL $bus val:double	MkBufferStreamWriteDBL_RT

write a PRIMITIVE TYPE into the MkBufferStreamC …

After every write the current-access-position is incremented by one, use MkBufferStreamC [MkBufferStreamC::Reset $bus] to reset.

Parameters

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

Exceptions

MkExceptionC

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

MkBufferStreamC MISC

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

MkBufferStreamC [MkBufferStreamC::Copy $bus src:MkBufferStreamC]

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

Parameters

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

Returns

the bus instance

MkBufferStreamC::Log $bus ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

top log the MkBufferStreamC … → API: atlmkkernel_MkObjectC_Log

Parameters

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

MkBufferStreamC::PosToStart $bus

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

MkBufferStreamC [MkBufferStreamC::Reset $bus]

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

Parameters

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

See also

MkBufferStreamC::ResetFull $bus

MkBufferStreamC::ResetFull $bus

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

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

Parameters

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

See also

MkBufferStreamC [MkBufferStreamC::Reset $bus]

MkBufferListC [MkBufferStreamC::ToBFL $bus]

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

Parameters

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

Returns

the MkBufferListC instance requested or MkBufferListGetNull on error

Note

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

string [MkBufferStreamC::ToString $inst]

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

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

See also

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

Parameters

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

Returns

the requested string or "MK_NULL" on error

Note

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

---

MkBufferListC

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

MkBufferListC DETAIL

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

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

MkBufferListC CLASS

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

C-Kernel-Details

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

‍0 <= index < MkBufferListS::cursize

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

‍A MkBufferListS never run out of storage.

See also

MkBufferC, MkBufferStreamC

MkBufferListC CTOR / DTOR

command	alias
(constructor,static) MkBufferListC [MkBufferListC::Create ?size:int32=0?]	myooX::NewN ::MkBufferListC ?num:I=0?
(destructor) MkBufferListC::Delete $bfl	myooX::DestroyN $bfl

MkBufferListC CLASS

NAVI: top, up

MkBufferListC CLASS EXPORT

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

MkBufferListC CLASS INTROSPECTION

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

MkBufferListC CLASS MISC

GetNull

Null-Slot - return a MkBufferListC typed NULL instance …

MkBufferListC CLASS DETAILS

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

MkBufferListC CLASS EXPORT

MkBufferListC - Export class functions …

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

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [MkBufferListC::HandleGet $bfl]

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

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

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

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

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

Parameters

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

Returns

the required export-hdl

MkBufferListC CLASS INTROSPECTION

MkBufferListC - Introspection class functions …

(static) MkBufferListC [MkBufferListC::Instances]

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

The head-instance is the last instance created.

MkBufferListC [MkBufferListC::Next $bfl]

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

MkBufferListC [MkBufferListC::Prev $bfl]

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

MkBufferListC CLASS MISC

MkBufferListC - Misc class functions …

(static) MkBufferListC [MkBufferListC::GetNull]

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

MkBufferListC TOR

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

(constructor,static) MkBufferListC [MkBufferListC::Create ?size:int32=0?]

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

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

Parameters

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

Returns

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

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

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

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

Returns

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

See also

BufferListDup

(static) MkBufferListC [MkBufferListC::CreateTLS tlsName:string ?resetB:bool=true?]

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

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

Example from perfserver.atl → performance test with TLS storage

  proc Ot_BFLT { myNs } {
    set bfl [MkBufferListC::CreateTLS "perfserver-BFLT" ]
    while {[ReadItemExists $myNs]} {
      MkBufferListC::AppendBUF $bfl [ReadBUF $myNs]
    }
    SendSTART $myNs
    set size [MkBufferListC::Size $bfl]
    for {set i 0} {$i < $size} {incr i} {
      SendBUF $myNs [MkBufferListC::IndexGet $bfl $i]
    }
    SendRETURN $myNs
  }

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

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

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

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

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

Parameters

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

Returns

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

Attention

for usage of the TLS-storage read more at StorageCreateTLS

(constructor,static) MkBufferListC [MkBufferListC::CTOR ?size:int32=0?]

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

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

Parameters

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

Returns

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

(destructor) MkBufferListC::Delete $bfl

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

There are two different ways to delete an instance:

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

Attention

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

See also

BufferListCreate BufferListDup MqReadBFL

(constructor) MkBufferListC [MkBufferListC::Dup $bfl]

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

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

Returns

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

See also

MkObjDup

(constructor) MkBufferListC [MkBufferListC::Merge $bfl]

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

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

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

Parameters

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

Returns

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

Attention

The new instance have to be deleted with BufferListDelete

See also

BufferListDup

MkBufferListC APPEND

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

MkBufferListC::AppendBUF $bfl val:MkBufferC

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

Parameters

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

Attention

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

MkBufferListC::AppendG $bfl val:long

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

Parameters

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

MkBufferListC [MkBufferListC::AppendLA $bfl args:MkBufferListC...]

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

Parameters

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

MkBufferListC [MkBufferListC::AppendLP $bfl addBufL:MkBufferListC ?position:int32=-1?]

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

Parameters

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

Attention

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

MkBufferListC::AppendStringR $bfl val:string

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

Parameters

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

MkBufferListC::AppendUP $bfl addBuf:MkBufferC ?position:int32=-1?

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

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

Parameters

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

Attention

After append the object addBuf will be owned by bfl.

MkBufferListC::AppendTT $bfl val:int8

top

The BufferListAppendTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
		MkBufferListC::AppendI8 $bfl val:int8	MkBufferListAppendI8_RT
		MkBufferListC::AppendI16 $bfl val:int16	MkBufferListAppendI16_RT
		MkBufferListC::AppendI32 $bfl val:int32	MkBufferListAppendI32_RT
		MkBufferListC::AppendI64 $bfl val:int64	MkBufferListAppendI64_RT
		MkBufferListC::AppendSTR $bfl val:string	MkBufferListAppendSTR_RT
		MkBufferListC::AppendBIN $bfl val:binary	MkBufferListAppendBIN_RT
		MkBufferListC::AppendBOL $bfl val:bool	MkBufferListAppendBOL_RT
		MkBufferListC::AppendFLT $bfl val:float	MkBufferListAppendFLT_RT
		MkBufferListC::AppendDBL $bfl val:double	MkBufferListAppendDBL_RT

append a native PRIMITIVE TYPE object to a MkBufferListC …

Parameters

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

MkBufferListC CHECK

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

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

bool [MkBufferListC::CheckOption $bfl opt:string ?onlyFirst:bool=false?]

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

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

Parameters

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

MkBufferC [MkBufferListC::CheckOptionBUF $bfl opt:string ?defval:MkBufferC=NULL? ?onlyFirst:bool=true?]

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

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

[MkBufferListC::CheckOptionTT $bfl opt:string ?defval:int8=0? ?onlyFirst:bool=true?]

top

The BufferListCheckOptionTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	int8	[MkBufferListC::CheckOptionI8 $bfl opt:string ?defval:int8=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionI8_RT
	int16	[MkBufferListC::CheckOptionI16 $bfl opt:string ?defval:int16=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionI16_RT
	int32	[MkBufferListC::CheckOptionI32 $bfl opt:string ?defval:int32=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionI32_RT
	int64	[MkBufferListC::CheckOptionI64 $bfl opt:string ?defval:int64=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionI64_RT
	string	[MkBufferListC::CheckOptionSTR $bfl opt:string ?defval:string=""? ?onlyFirst:bool=true?]	MkBufferListCheckOptionSTR_RT
	bool	[MkBufferListC::CheckOptionBOL $bfl opt:string ?defval:bool=false? ?onlyFirst:bool=true?]	MkBufferListCheckOptionBOL_RT
	float	[MkBufferListC::CheckOptionFLT $bfl opt:string ?defval:float=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionFLT_RT
	double	[MkBufferListC::CheckOptionDBL $bfl opt:string ?defval:double=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionDBL_RT

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

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

MkBufferListC INDEX

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

MkBufferListC::IndexDelete $bfl index:int32 ?numitems:int32=1? ?doDelete:bool=true?

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

Parameters

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

Exceptions

MkExceptionC

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

MkBufferC [MkBufferListC::IndexGet $bfl index:int32]

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

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

See also

BufferListIndexGetBUF

MkBufferC [MkBufferListC::IndexGetBUF $bfl index:int32]

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

The buffer returned is still owned by bfl.

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

Parameters

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

Returns

the MkBufferC requested

See also

BufferListIndexGet

string [MkBufferListC::IndexGetSTR $bfl index:int32]

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

for details please refer to BufferListIndexGetBUF.

Parameters

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

Returns

the string requested or an EMPTY-STRING on error

MkBufferListC::IndexSet $bfl index:int32 buf:MkBufferC

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

It is an error if index is not available.

See also

BufferListIndexSetBUF

MkBufferListC::IndexSetBUF $bfl index:int32 buf:MkBufferC

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

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

Parameters

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

MkBufferListC::IndexSetSTR $bfl index:int32 str:string

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

for details please refer to BufferListIndexGetBUF

Parameters

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

MkBufferC [MkBufferListC::IndexExtract $bfl ?index:int32=0?]

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

If the index is not available, this is an error

Parameters

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

Exceptions

MkExceptionC

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

Attention

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

See also

BufferListDelete

MkBufferListC LOG

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

MkBufferListC::Log $bfl ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

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

Parameters

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

See also

MkBufferListC

MkBufferListC::LogS $bfl ?varname:string="bfl"? ?fmtobj:MkObjectC=NULL? ?callfunc:string="MK_NULL"?

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

Parameters

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

MkBufferListC::LogSS $bfl ?varname:string="bfl"? ?fmtobj:MkObjectC=NULL? ?callfunc:string="MK_NULL"?

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

Parameters

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

MkBufferListC::LogSSS $bfl ?varname:string="bfl"? ?fmtobj:MkObjectC=NULL? ?callfunc:string="MK_NULL"?

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

Parameters

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

MkBufferListC MISC

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

(constructor,static) MkBufferListC [MkBufferListC::FileGlob pattern_match:string]

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

MkBufferListC::Move $to from:MkBufferListC

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

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

Parameters

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

MkBufferListC::Copy $bfl src:MkBufferListC

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

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

Parameters

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

MkBufferListC [MkBufferListC::PositionMerge $bfl source:MkBufferListC position:int32]

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

Parameters

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

int32 [MkBufferListC::Cmp $bfl bfl2:MkBufferListC]

top compare two buffer-list … → API: atlmkkernel_MkBufferListC_Cmp

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

Parameters

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

Returns

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

MkBufferListC::Reserve $bfl num:int32

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

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

Parameters

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

MkBufferListC [MkBufferListC::Reset $bfl]

top reset a MkBufferListC object … → API: atlmkkernel_MkBufferListC_Reset

Parameters

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

Attention

all MkBufferC objects will be freed

int32 [MkBufferListC::SearchC $bfl str:string ?len:int32=-1? ?startindex:int32=0?]

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	bfl	the MkBufferListS instance to work on
	str	the string to search for
	len	the length of str or -1 to calulate the length with strlen
	startindex	start searching in buf from index startindex

Returns

The index of the str found or -1 if not found. The return value can be used as startindex of following calls to BufferListSearchC

a typical usage for this code is parsing an MkBufferListS object for multiple occurrences of a string

while ((startindex = MkBufferListSearchC (buf, str, strlen(str), startindex)) != -1) {
  ...
}

Attention

The size of str have to be at least 4 bytes

int32 [MkBufferListC::Size $bfl]

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

Parameters

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

Returns

the number-of-items in the bfl

MkBufferListC [MkBufferListC::Sort $bfl]

top sort a MkBufferListC … → API: atlmkkernel_MkBufferListC_Sort

Parameters

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

Returns

Return the input bfl as sorted list

MkBufferC [MkBufferListC::ToBuffer $bfl]

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

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

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

Parameters

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

Returns

the required buffer or a "MK_NULL" on error

Attention

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

[list...] [MkBufferListC::ToList $bfl]

top get a target-language list representation of the bfl … → API: MkBufferListToList_RT

Parameters

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

Returns

the required list

Attention

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

string [MkBufferListC::ToString $bfl]

top get a string representation of the bfl → API: atlmkkernel_MkObjectC_ToString

Parameters

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

Returns

the required string

Attention

• The returned string is owned by self… do not free.
• On error an empty string is returned.

---

MkErrorC

MkErrorC CLASS
		Export	MkErrorC - Export class functions …
		Introspection	MkErrorC - Introspection class functions …
		Misc	MkErrorC - Misc class functions …
MkErrorC TOR
		Delete	Destructor - delete a MkErrorS object …
		Copy	Copy-Constructor - sync an existing MkErrorC instance with the values from an existing MkErrorC instance …
		Dup	Dup-Constructor - create a new MkErrorC instance as copy from an existing MkErrorC instance …
MkErrorC GET
		GetCode	get the value of MkErrorS::code …
		GetNum	get the MkErrorS::num. The number can be used as exit-code …
		GetSize	get the error-message-size from the exception-object …
		GetText	get the MkErrorS::text …
MkErrorC RAISE
		PanicC	do a panic with string as argument …
		PanicDEFAULT	make panic from MkErrorDEFAULT_RT …
		AppendC	append the message to the MkErrorS::text …
		NoRaise	ignore the next return of MK_ERROR and do not raise an target-language-exception …
		Raise	convert an atlmkkernel error into an programming-language-error and raise afterwards. …
		SetC	'set' and 'raise' the MkErrorC using a string-message and a errnum-number …
MkErrorC SIGNAL
		IsABORT	check on ABORT signal …
		IsEXIT	check on APPLICATION-EXIT error …
		IsSOCKET	check on SOCKET-DOWN error …
		IsTIMEOUT	check on TIMEOUT error …
		SetABORT	send the ABORT signal to the calling stack…
		SetCode	set the MkErrorS::code value …
		SetCONTINUE	signal end of processing in an MqMqEventIF callback …
		SetEXIT	finish the current callback, return to toplevel and MqExit the application …
		SetSOCKET	create SOCKET-DOWN error …
MkErrorC SYSTEM
		DEFAULT	default-system-error - default-error …
		FORMAT	system-error-format - format and return the default-error …
		IGNORE	ignore-system-error - ignore the next error …
		PRINT	ignore-system-error - print the next error into MkLogFileC …
MkErrorC MISC
		Catch	convert a programming-language-error into an atlmkkernel error …
		Cleanup	cleanup and print unwanted active error …
		Log	log the error to MkLogFileC (default: stderr) …
		Println	print the default-error to the MkLogFileC (default: stderr) and clear the error afterwards …
		Reset	This function clears the err and resets to MK_OK …
		Stack	check on error and if yes append an ErrorStackFormat to the error-message …
		StackFormat	append an ensemble of func, file and line to the error-message …
		ToString	String-Slot - returns the string representation of the inst …

MkErrorC DETAIL

C-API: MkErrorC_C_API - MkErrorC - the class known as err or error is used to create and manage an error message …

An error is a singleton object per thread created at startup and is located at MkRuntimeRLS using the datatype MkErrorC.

‍As error-indicator the enum 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 atlmkkernel into the error-handling-code of the target Atl.

Example from Filter6.atl → use MqContextErrorCatch to convert a Atl error into a atlmkkernel error

MqMsgque::Main {
  set srv [MqFactoryC::New [MqFactoryC::Add ::Filter6]]
  try {
    MqContextC::LinkCreate $srv {*}$argv
    MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER
  } on error {} {
    MqContextC::ErrorCatch $srv
  } finally {
    MqContextC::Exit $srv
  }
}

MkExceptionC

MkExceptionC - The default-exception of the Programming-Language-Micro-Kernel (PLMK) …

The Programming-Language-Micro-Kernel (PLMK) provide with MkErrorC a complete error-handling with focus to support the "C" Programming-Language. The support include catch, raise, signal and attributes. In addition every Target-Programming-Language (TPL) add their own error-handling and the purpose of MkExceptionC is to integrate the MkErrorC into the Target-Programming-Language (TPL).

The default-exception MkExceptionC is used to connect the MkErrorC with the Target-Programming-Language (TPL) error-object.

• The default-error is defined in MkRuntimeS::error_mk.
• On error the default-error is set to the error-data, the MkErrorE status change to MK_ERROR.
• The non-C language create a copy from the default-error and throw the copy as MkExceptionC exception.
• The C language just return the MkErrorE status of the default-error.

The implementation of an exception depends heavily on the Target-Programming-Language (TPL), starting with no exception at all, for example. C, an exception as a class object, or as an exception as a global attribute.

Attention

• All MkExceptionC code is implemented at the Target-Programming-Language (TPL) without support by the Programming-Language-Micro-Kernel (PLMK) compiler.
• By default, MkExceptionC is only used internally, hidden by the class MkErrorC.

ExceptionCheck

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

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

        set VAL   [ReadBUF $myNs]
        set cl    [myooX::NewN ::Client]
        Client::myLinkCreate $cl [ConfigGetStartAs $myNs]
        Send $cl "W" "GPID@I" PID
        SysKill $myNs $PID 9
        set RET 0
        foreach num {1 2 3} {
          try {
            set RET [Send $cl "W" "ECOI:U@I" $VAL]
          } trap {MkExceptionC} "" {
            set err [ErrorCatch $cl]
            if {[MkErrorC::IsSOCKET $err]} {
              MkErrorC::Reset $err
              LinkConnect $cl
              continue
            } else {
              MkErrorC::Raise $err
            }
            myooX::DestroyN $err
          }
          break
        }
        SendSTART $myNs
        SendI32 $myNs $RET

Returns

the result of the check, true or false

Parameters

[in]

exception

the exception object from Atl, if "MK_NULL" the global exception object is used

MkErrorC CLASS

NAVI: top, up

MkErrorC CLASS EXPORT

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

MkErrorC CLASS INTROSPECTION

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

MkErrorC CLASS MISC

GetNull

Null-Slot - return a MkErrorC typed NULL instance …

MkErrorC CLASS DETAILS

C-API: MkErrorC_Class_C_API - MkErrorC - define the class …

MkErrorC CLASS EXPORT

MkErrorC - Export class functions …

(static) MkErrorC [MkErrorC::HandleResolve netHdl:MK_HDL]

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [MkErrorC::HandleGet $err]

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

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

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

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

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

Parameters

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

Returns

the required export-hdl

MkErrorC CLASS INTROSPECTION

MkErrorC - Introspection class functions …

(static) MkErrorC [MkErrorC::Instances]

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

The head-instance is the last instance created.

MkErrorC [MkErrorC::Next $err]

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

MkErrorC [MkErrorC::Prev $err]

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

MkErrorC CLASS MISC

MkErrorC - Misc class functions …

(static) MkErrorC [MkErrorC::GetNull]

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

MkErrorC TOR

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

(destructor) MkErrorC::Delete $err

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

There are two different ways to delete an instance:

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

Attention

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

See also

BufferDup ObjectDelete

MkErrorC::Copy $dest srce:MkErrorC

top Copy-Constructor - sync an existing MkErrorC instance with the values from an existing MkErrorC instance … → API: atlmkkernel_MkErrorC_Copy

See also

MkObjDup MkErrorDelete

(constructor) MkErrorC [MkErrorC::Dup $srce]

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

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

Returns

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

See also

MkObjDup MkErrorDelete

MkErrorC GET

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

MkErrorE [MkErrorC::GetCode $err]

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

int32 [MkErrorC::GetNum $err]

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

long [MkErrorC::GetSize $err]

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

string [MkErrorC::GetText $err]

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

MkErrorC RAISE

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

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

(static) MkErrorC::PanicC fmtobj:MkObjectC callfunc:string errnum:int32 message:string

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	fmtobj	managed object used to format the log-message (default="MK_NULL" → use default-format)
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)
[in]	errnum	the error number used as exit-code as well
	message	the string to be displayed

Attention

this function will never return

(static) MkErrorC::PanicDEFAULT ?fmtobj:MkObjectC=NULL? ?callfunc:string="MK_NULL"?

top make panic from MkErrorDEFAULT_RT … → API: atlmkkernel_MkErrorC_PanicDEFAULT

Parameters

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

Attention

this function will never return

MkErrorC::AppendC $err message:string

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

Parameters

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

MkErrorC [MkErrorC::NoRaise $err]

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

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

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

This is usefull if:

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

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

  proc bgError { myNs } {
    set master [SlaveGetMaster $myNs]
    if {$master ne ""} {
      set err [MkErrorC::NoRaise [ErrorFORMAT $master]]
      MkErrorC::SetC $err [MkErrorC::GetText $err] "BGERROR" [MkErrorC::GetNum $err]
      SendERROR $master
    }
  }

Parameters

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

Returns

the input err with MkErrorS::noRaise flag set

MkErrorC::Raise $err

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

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

MkErrorC::SetC $err message:string ?callfunc:string="MK_NULL"? ?errnum:int32=-1?

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

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed) - err==NULL allowed
[in]	message	the string to be displayed as message
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)
[in]	errnum	the error number used as exit-code as well

Attention

Use ErrorNoRaise to avoid raise an error.

MkErrorC SIGNAL

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

bool [MkErrorC::IsABORT $err]

top check on ABORT signal … → API: atlmkkernel_MkErrorC_IsABORT

bool [MkErrorC::IsEXIT $err]

top check on APPLICATION-EXIT error … → API: atlmkkernel_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/atl/Filter4.atl example

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

if (MkErrorCheckI (MqSendEND_AND_WAIT (ctx, "TOKS", MK_TIMEOUT_USER))) {
  if (MkErrorIsEXIT_0E ()) MkErrorReset_1X (ctx);
}

bool [MkErrorC::IsSOCKET $err]

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

bool [MkErrorC::IsTIMEOUT $err]

top check on TIMEOUT error … → API: atlmkkernel_MkErrorC_IsTIMEOUT

MkErrorC::SetABORT $err ?detail:string="UNKNOWN"? ?callfunc:string="MK_NULL"?

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

The ABORT-signal is used to disrupt the current execution like an error and unwind the calling stack. The MkErrorIsABORT is used to detect the ABORT-signal and MkErrorReset is used to clear the ABORT-signal

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	detail	add additional detail information
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)

MkErrorC::SetCode $err code:MkErrorE

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

MkErrorC::SetCONTINUE $err

top signal end of processing in an MqMqEventIF callback … → API: atlmkkernel_MkErrorC_SetCONTINUE

MkErrorC::SetEXIT $err ?callfunc:string="MK_NULL"?

top finish the current callback, return to toplevel and MqExit the application … → API: atlmkkernel_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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)

MkErrorC::SetSOCKET $err ?detail:string="UNKNOWN"? ?callfunc:string="MK_NULL"?

top create SOCKET-DOWN error … → API: atlmkkernel_MkErrorC_SetSOCKET

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	detail	add additional detail information
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)

MkErrorC SYSTEM

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

(static) MkErrorC [MkErrorC::DEFAULT]

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

The default-error is defined once per runtime and is used as only-valid-source of an MkErrorC in a thread or process.

See also

ErrorFORMAT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC, RMkNsRT{ErrorEXIT}

(static) MkErrorC [MkErrorC::FORMAT ?fmtobj:MkObjectC=NULL?]

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

Returns

the MkErrorS::format_of_error or MkErrorS::source_of_error attribute

MkErrorFORMAT - usage

Set the MkErrorS::format_of_error attribute to fmtobj or "MK_NULL". The next error-message will be formated as usual and than be raised as error. The default-error will be modified.

The next error-message created with ErrorSetC etc is formatted with MkRuntimeS->cid ("context-in-duty") or simply as "DEFAULT" if cid == NULL.

Parameters

[in]

fmtobj

managed object used to format the log-message (default="MK_NULL" → use default-format)

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC, RMkNsRT{ErrorEXIT}

(static) MkErrorC [MkErrorC::IGNORE]

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

The next error will be ignored, no formatting will be performed and the the default-error will not be modified.

MkErrorIGNORE - usage

There are two functions to suppress an error: MkErrorIGNORE and MkErrorNoRaise.

MkErrorIGNORE

Set the MkErrorS::format_of_error attribute to IGNORE. The next error will be ignored, no formatting will be performed and the the default-error will not be modified.

MkErrorNoRaise

Set the MkErrorS::noRaise attribute to TRUE. The next error will be set as usual but not raised. This is usefull to set an error and later append additional information to the error. Final the error have to be raised with MkErrorRaise.

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC, RMkNsRT{ErrorEXIT}

(static) MkErrorC [MkErrorC::PRINT]

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

The next error-message will be formated as usual and than be reported using MkLogVL. The default-error will not be modified.

MkErrorPRINT - usage

Set the MkErrorS::format_of_error attribute to PRINT.

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC, RMkNsRT{ErrorEXIT}

MkErrorC MISC

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

MkErrorC [MkErrorC::Catch $err ?exception:errorCode=NULL? ?callfunc:string="MK_NULL"?]

top convert a programming-language-error into an atlmkkernel error … → API: atlmkkernel_MkErrorC_Catch

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

Example from Bug3.atl → catch an error using MkErrorC [MkErrorC::Catch $err ?exception:errorCode=NULL? ?callfunc:string="MK_NULL"?]

  } on error {} {

    MkErrorC::Println [ MkErrorC::Catch [MkErrorC::DEFAULT] ] 
  }

Note

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

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	exception	the exception object from Atl, if "MK_NULL" the global exception object is used
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)

Returns

the ErrorDEFAULT initialized with exception value

See also

ObjectErrorCatch ErrorRaise ErrorReset

MkErrorC::Cleanup $err ?callfunc:string="MK_NULL"? ?callline:int32=-1?

top cleanup and print unwanted active error … → API: atlmkkernel_MkErrorC_Cleanup

‍It is an error if an active-error from MkERROR (MkRuntimeS::error_mk) is not consumed.

To detect an error, the error-code (MkErrorE) of the function return is normally evaluated, which is initially completely independent of the error-code (MkErrorS::code) from MkERROR but still in sync.

• However, this mechanism is disrupted if an unconsumed-error already exists when the function is started, which is why an error in MkERROR exists despite the function returning MK_OK.

MkErrorCleanup reports and deletes an error that already exists when the function starts.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)
[in]	callline	the number of the line the call take place (e.g. LINE)

See also

MkErrorReset, MkErrorPrintln

MkErrorC::Log $err ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

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

Parameters

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

See also

MkErrorC MkErrorC::Log $err ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

MkErrorC::Println $err ?msg:string=""? ?callfunc:string="MK_NULL"? ?callline:int32=-1?

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	msg	additional info to explane the error and the reset
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)
[in]	callline	the number of the line the call take place (e.g. LINE)

MkErrorC::Reset $err ?callfunc:string="MK_NULL"? ?callline:int32=-1? ?force:bool=false?

top This function clears the err and resets to MK_OK … → API: atlmkkernel_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 [MkErrorC::Stack $err ?callfunc:string="MK_NULL"? ?callfile:string="MK_NULL"? ?callline:int32=-1?]

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed) → "MK_NULL" allowed
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)
[in]	callfile	the name of the file the call take place (e.g. FILE)
[in]	callline	the number of the line the call take place (e.g. LINE)

Exceptions

MkExceptionC

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

MkErrorC::StackFormat $err ?callfunc:string="MK_NULL"? ?callfile:string="MK_NULL"? ?callline:int32=-1?

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)
[in]	callfile	the name of the file the call take place (e.g. FILE)
[in]	callline	the number of the line the call take place (e.g. LINE)

string [MkErrorC::ToString $inst]

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

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

See also

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

Parameters

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

Returns

the requested string or "MK_NULL" on error

Note

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

---

MkLogFileC

MkLogFileC CLASS
		Export	MkLogFileC - Export class functions …
		Introspection	MkLogFileC - Introspection class functions …
		Misc	MkLogFileC - Misc class functions …
MkLogFileC TOR
		Open	open the log-file in append mode …
		CTOR	open the log-file in append mode …
		Close	Destructor - delete a MkLogFileC instance …
MkLogFileC WRITE
		GetFile	get the log-file …
		WriteC	write to log-file …

MkLogFileC DETAIL

C-API: MkLogFileC_C_API - MkLogFileC - the class known as lfl or log-file is used to control the target of the logging-output …

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

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

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

possible values are:

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

MkLogFileC CLASS

NAVI: top, up

MkLogFileC CLASS EXPORT

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

MkLogFileC CLASS INTROSPECTION

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

MkLogFileC CLASS MISC

GetNull

Null-Slot - return a MkLogFileC typed NULL instance …

MkLogFileC CLASS DETAILS

C-API: MkLogFileC_Class_C_API - MkLogFileC - define the class …

MkLogFileC CLASS EXPORT

MkLogFileC - Export class functions …

(static) MkLogFileC [MkLogFileC::HandleResolve netHdl:MK_HDL]

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [MkLogFileC::HandleGet $lfl]

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

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

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

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

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

Parameters

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

Returns

the required export-hdl

MkLogFileC CLASS INTROSPECTION

MkLogFileC - Introspection class functions …

(static) MkLogFileC [MkLogFileC::Instances]

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

The head-instance is the last instance created.

MkLogFileC [MkLogFileC::Next $lfl]

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

MkLogFileC [MkLogFileC::Prev $lfl]

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

MkLogFileC CLASS MISC

MkLogFileC - Misc class functions …

(static) MkLogFileC [MkLogFileC::GetNull]

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

MkLogFileC TOR

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

(constructor,static) MkLogFileC [MkLogFileC::Open fmtobj:MkObjectC file:string]

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

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	fmtobj	managed object used to format the log-message (default="MK_NULL" → use default-format)
[in]	file	the filename to open
[out]	lfh_out	returns

Returns

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

Exceptions

MkExceptionC

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

Attention

on error the lfh_out is set to "MK_NULL"

(constructor,static) MkLogFileC [MkLogFileC::CTOR fmtobj:MkObjectC file:string]

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

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	fmtobj	managed object used to format the log-message (default="MK_NULL" → use default-format)
[in]	file	the filename to open
[out]	lfh_out	returns

Returns

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

Exceptions

MkExceptionC

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

Attention

on error the lfh_out is set to "MK_NULL"

(destructor) MkLogFileC::Close $lfh

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

There are two different ways to delete an instance:

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

Attention

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

See also

LogFileOpen

MkLogFileC WRITE

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

string [MkLogFileC::GetFile $lfl]

top get the log-file … → API: atlmkkernel_MkLogFileC_GetFile

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	lfl	the MkLogFileS instance to work on
[out]	file_out	the log-file to return

Exceptions

MkExceptionC

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

MkLogFileC::WriteC $lfl text:string

top write to log-file … → API: atlmkkernel_MkLogFileC_WriteC

Parameters

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

Exceptions

MkExceptionC

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

---

MkRuntimeC

MkRuntimeC CONFIG
		DebugGet	get the MkRuntimeS::debug value …
		DebugSet	set the MkRuntimeS::debug value …
		ErrorGetCode	return MkErrorS::code from a given MkRuntimeC …
		IsSilentGet	get the MkRuntimeS::isSilent value …
		IsSilentSet	set the MkRuntimeS::isSilent value …
		LogTargetGet	get the MkLogDataS::logNAME value …
		LogTargetReset	set the MkRuntimeS::log value to the DEFAULT value …
		LogTargetSet	set the MkRuntimeS::log value and cleanup old value …
		NoDecoSet	set the MkRuntimeS::noDeco value …
MkRuntimeC INFO
		Log0	log the MkRuntimeC …

MkRuntimeC DETAIL

C-API: MkRuntimeC_C_API - MkRuntimeC - The class known as mkrt or runtime is the main atlmkkernel application environment …

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

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

runtime-separation

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

the runtime provide the following features

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

THREAD ENABLED LIBRARY

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

RUNTIME DEFAULT

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

MkRuntimeC CONFIG

C-API: MkRuntimeC_Config_C_API - MkRuntimeC - various functions to configure the MkRuntimeRLS (only C) …

The MkRuntimeRLS-configuration belongs to a single MkRuntimeRLS. In a threadable application, each thread has its own MkRuntimeRLS and therefore its own configuration.

A function ending in 'I' is the inline variant of the function without the 'I' and is preferred in C.

(static) int32 [MkRuntimeC::DebugGet]

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

(static) MkRuntimeC::DebugSet dbg:int32

top set the MkRuntimeS::debug value … → API: atlmkkernel_MkRuntimeC_DebugSet

(static) MkErrorE [MkRuntimeC::ErrorGetCode]

top return MkErrorS::code from a given MkRuntimeC … → API: atlmkkernel_MkRuntimeC_ErrorGetCode

(static) bool [MkRuntimeC::IsSilentGet]

top get the MkRuntimeS::isSilent value … → API: atlmkkernel_MkRuntimeC_IsSilentGet

(static) MkRuntimeC::IsSilentSet silent:bool

top set the MkRuntimeS::isSilent value … → API: atlmkkernel_MkRuntimeC_IsSilentSet

(static) string [MkRuntimeC::LogTargetGet]

top get the MkLogDataS::logNAME value … → API: atlmkkernel_MkRuntimeC_LogTargetGet

Attention

the string is owned by atlmkkernel -> do not free !!

(static) MkRuntimeC::LogTargetReset

top set the MkRuntimeS::log value to the DEFAULT value … → API: atlmkkernel_MkRuntimeC_LogTargetReset

See also

MkRuntimeLogTargetSet

(static) MkRuntimeC::LogTargetSet logTgt:string

top set the MkRuntimeS::log value and cleanup old value … → API: atlmkkernel_MkRuntimeC_LogTargetSet

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	logTgt	one of: STDERR ("",NULL,default), STDOUT, BUFFER, filename

(static) MkRuntimeC::NoDecoSet noDeco:bool

top set the MkRuntimeS::noDeco value … → API: atlmkkernel_MkRuntimeC_NoDecoSet

MkRuntimeC INFO

C-API: MkRuntimeC_Info_C_API - MkRuntimeC - various functions to print information about the rt …

(static) MkRuntimeC::Log0 ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

top log the MkRuntimeC … → API: atlmkkernel_MkRuntimeC_Log0

Parameters

[in]	mkrt	The runtime to log, (default="MK_NULL" → use the doc_mk_atl_runtime-default)
[in]	fmtobj	managed object used to format the log-message (default="MK_NULL" → use default-format)
[in]	debug	the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]	callfunc	a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name)
[in]	lvl	a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)

See also

MkRuntimeC

---

BINARY OBJECT

No special binary-object is used. All binary-data is available as Atl binary.

---

EXAMPLES

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

  proc Ot_BUF2 { myNs } {
    SendSTART $myNs

    foreach i {1 2 3} {
      set buf [ReadBUF $myNs]
      SendSTR $myNs [MkBufferC::GetType1 $buf]
      SendBUF $myNs $buf
      myooX::DestroyN $buf
    }

    SendRETURN $myNs
  }

---

SEE ALSO

libmkkernel, ccmkkernel, csmkkernel, javamkkernel, gomkkernel, pymkkernel, rbmkkernel, tclmkkernel, perlmkkernel, phpmkkernel

KEYWORDS

Atl, unix, socket, message, msgque