tclmkkernel

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

SYNOPSIS

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

• package require tclmkkernel 

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

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

To access all features without tclmkkernel prefix use:

• namespace import tclmkkernel::* 

Using the tclmkkernel package ...

TCL package libraries

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

libtclmkkernel.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 tclmkkernel 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]]

---

TABLE OF CONTENTS

BASICS

Philosophy , Package , ManagedObject , PrimitiveTypes , StorageManagement ,

CLASS

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

MISC

BinaryObject, Examples

INTRODUCTION

C-API: MK_C_API - The LibMkKernel API …

PHILOSOPHY

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

Philosophy

Write Once → Run Everywhere

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

Strategy

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

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

Conclusion

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

PROGRAMMING

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

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

library-layer

The library-layer implement the tclmkkernel 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 Tcl programmer. !!

PACKAGE

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

The tclmkkernel package is loaded with:

‍

package require tclmkkernel 

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

The tclmkkernel 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 tclmkkernel application environment …

The tclmkkernel package add the following public types into MkObjectC_C_API :

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

MANAGED OBJECT

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

tclmkkernel is also called as Programming-Language-Micro-Kernel (PLMK). tclmkkernel is like a programming-language without syntax but using the Target-Programming-Language (in our case Tcl) 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 tclmkkernel 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 tclmkkernel-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 tclmkkernel to provide temporary storage. It is a common design pattern that tclmkkernel 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 tclmkkernel 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 Tcl 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 tclmkkernel 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.tcl → ReadBFL overwrite previous ReadBFL

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

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

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

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

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

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

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

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

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

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

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

Attention

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

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

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

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

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

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

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

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

---

MkKernel PACKAGE

MkKernel SETUP			MkKernel PACKAGE - Setup und Cleanup the tclmkkernel …
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 tclmkkernel package is loaded with:

‍

package require tclmkkernel 

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

The tclmkkernel 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 tclmkkernel application environment …

The tclmkkernel package add the following public types into MkObjectC_C_API :

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

MkKernel SETUP

NAVI: top, up

		Cleanup	cleanup tclmkkernel internal memory …
		Setup	setup tclmkkernel internal memory …

MkKernel SETUP DETAILS

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

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

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

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

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

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

shared library detail

A new tclmkkernel 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 tclmkkernel 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 tclmkkernel library must be known when the thread starts. This is not a problem as long as the external tclmkkernel library is linked to the application. However, if dlopen is used to load the tclmkkernel library, the current restriction is that the new data type from the tclmkkernel 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 tclmkkernel internal memory … → API: tclmkkernel_MkKernel_Cleanup

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

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

Attention

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

(static) MkKernel Setup

top setup tclmkkernel internal memory … → API: tclmkkernel_MkKernel_Setup

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

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

MkKernel ENUM

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

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

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

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

enum MkErrorE

top collection for the different error-codes … → API: tclmkkernel_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: tclmkkernel_MkKernel_ErrorE_FromInt

(static) int32 [MkKernel ErrorE_ToInt value:MkErrorE]

top return the MkErrorE as integer … → API: tclmkkernel_MkKernel_ErrorE_ToInt

(static) string [MkKernel ErrorE_ToString value:MkErrorE]

top return the MkErrorE as string … → API: tclmkkernel_MkKernel_ErrorE_ToString

enum MkIdSE

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

(static) MkIdSE [MkKernel IdSE_FromInt value:int32]

top return the MkIdSE from integer … → API: tclmkkernel_MkKernel_IdSE_FromInt

(static) int32 [MkKernel IdSE_ToInt value:MkIdSE]

top return the MkIdSE as integer … → API: tclmkkernel_MkKernel_IdSE_ToInt

(static) string [MkKernel IdSE_ToString value:MkIdSE]

top return the MkIdSE as string … → API: tclmkkernel_MkKernel_IdSE_ToString

enum MkTimeoutE

top Predefined Timeout values … → API: tclmkkernel_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: tclmkkernel_MkKernel_TimeoutE_FromInt

(static) int32 [MkKernel TimeoutE_ToInt value:MkTimeoutE]

top return the MkTimeoutE as integer … → API: tclmkkernel_MkKernel_TimeoutE_ToInt

(static) string [MkKernel TimeoutE_ToString value:MkTimeoutE]

top return the MkTimeoutE as string … → API: tclmkkernel_MkKernel_TimeoutE_ToString

enum MkTypeE

top basic data-types supported by Programming-Language-Micro-Kernel (PLMK) … → API: tclmkkernel_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: tclmkkernel_MkKernel_TypeE_FromInt

(static) int32 [MkKernel TypeE_ToInt value:MkTypeE]

top return the MkTypeE as integer … → API: tclmkkernel_MkKernel_TypeE_ToInt

(static) string [MkKernel TypeE_ToString value:MkTypeE]

top return the MkTypeE as string … → API: tclmkkernel_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-Tcl-Instance and the tclmkkernel-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 …
		LogDetail	log the MkObjectS verbose into the MkLogFileC (default: stderr) …
		LogSimple	log the MkObjectS into the MkLogFileC (default: stderr) …
MkObjectC MISC
		ErrorCatch	convert a programming-language-error into an tclmkkernel 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 Tcl-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 …

tclmkkernel is also called as Programming-Language-Micro-Kernel (PLMK). tclmkkernel is like a programming-language without syntax but using the Target-Programming-Language (in our case Tcl) 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 tclmkkernel 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: tclmkkernel_MkObjectC_HandleDeleteByNetHdl

(static) MkObjectC [MkObjectC HandleResolve netHdl:MK_HDL]

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

$netObj HandleDelete

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

bool [$obj HandleExists]

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

Parameters

[in]

obj

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

Returns

true or false

MK_HDL [$obj HandleGet]

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

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

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

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

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

Parameters

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

Returns

the required export-hdl

MK_HDL [$obj HandleGetOfType]

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

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

Parameters

[in]

obj

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

Returns

the required typeHdl

MK_HDL [$obj HandleGetOr0]

top return export-hdl or 0 in not created… → API: tclmkkernel_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: tclmkkernel_MkObjectC_Instances

The head-instance is the last instance created.

MkObjectC [$obj Next]

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

MkObjectC [$obj Prev]

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

MkObjectC CLASS MISC

MkObjectC - Misc class functions …

(static) MkObjectC [MkObjectC GetNull]

top Null-Slot - return a MkObjectC typed NULL instance … → API: tclmkkernel_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: tclmkkernel_MkObjectC_DeleteCallbackCleanup

See also

MkObjectDeleteCallbackSetup

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

top Create/Delete the instance-delete-callback … → API: tclmkkernel_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

MkObjectDeleteCallbackSetup : callback example

Read more at: Callback example

(destructor) $obj Delete

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

There are two different ways to delete an instance:

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

Attention

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

(destructor) $obj Dispose

top Dispose-Slot - untie the connection between the Native-Tcl-Instance and the tclmkkernel-Instance. → API: tclmkkernel_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: tclmkkernel_MkObjectC_DbgM

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

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

Attention

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

$fmtobj DbgL 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: tclmkkernel_MkObjectC_DbgL

The marker is prefixed with object data from th fmtobj.

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

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

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

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

Parameters

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

This function can be overwritten in the target programming language.

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

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

MkObjectC LOG

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

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

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

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

possible values are:

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

Many logging functions have common parameters:

Parameters

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

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

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

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

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

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

Parameters

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

$fmtobj LogHEX callfunc:string data:binary

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

Parameters

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

$obj Log ?fmtobj:MkObjectC="MK_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: tclmkkernel_MkObjectC_Log

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

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

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

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

Example: logging of a buffer object in RUBY :

require "rbmkkernel"
include MkKernel

buf = MkBufferC.CreateSTR("Hallo World")

buf.Log()

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

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

Parameters

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

See also

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

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

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

Parameters

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

See also

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

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

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

Parameters

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

See also

MkObjectC

MkObjectC MISC

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

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

top convert a programming-language-error into an tclmkkernel error … → API: tclmkkernel_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 tclmkkernel-error.

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

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

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

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

Note

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

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

Parameters

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

Returns

the ErrorDEFAULT initialized with exception value

See also

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

bool [$obj IsNull]

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

MkErrorC [$obj ToError]

top Error-Slot - return an error-object pre initialized with obj data. → API: tclmkkernel_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 tclmkkernel 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 [$obj ToName]

top Info-Slot - returns brief information about the obj as a string → API: tclmkkernel_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 tclmkkernel 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 [$obj ToNameOfClass]

top Class-Slot - returns the Tcl-Class-Name of the obj as string → API: tclmkkernel_MkObjectC_ToNameOfClass

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

ObjectToNameOfType	returns the name of the tclmkkernel type
ObjectToNameOfClass	returns the name of the Tcl class

string [$obj ToNameOfType]

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

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

ObjectToNameOfType	returns the name of the libmsgque type
ObjectToNameOfClass	returns the name of the Tcl 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 [$inst ToString]

top String-Slot - returns the string representation of the inst … → API: tclmkkernel_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 tclmkkernel 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) …
		new	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
		AppendSTR	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 tclmkkernel is working on data… tclmkkernel 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?]	tclmkkernel::MkBufferC new ?size:W=0?
(destructor) $buf Delete	rename $buf ""

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

  method Ot_BUF2 {} {
    my SendSTART

    foreach i {1 2 3} {
      set buf [my ReadBUF]
      my SendSTR [$buf GetType1]
      my SendBUF $buf
      $buf Delete
    }

    my SendRETURN
  }

See also

BufferGetType1 BufferGetType2 BufferGetType3

MkBufferC CLASS

NAVI: top, up

MkBufferC CLASS EXPORT

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

MkBufferC CLASS INTROSPECTION

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

MkBufferC CLASS MISC

GetNull

Null-Slot - return a MkBufferC typed NULL instance …

MkBufferC CLASS DETAILS

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

MkBufferC CLASS EXPORT

MkBufferC - Export class functions …

(static) MkBufferC [MkBufferC HandleResolve netHdl:MK_HDL]

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [$buf HandleGet]

top Handle-Get-Slot - returns a export-hdl to the MkBufferC useable for external storage → API: tclmkkernel_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: tclmkkernel_MkBufferC_Instances

The head-instance is the last instance created.

MkBufferC [$buf Next]

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

MkBufferC [$buf Prev]

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

MkBufferC CLASS MISC

MkBufferC - Misc class functions …

(static) MkBufferC [MkBufferC GetNull]

top Null-Slot - return a MkBufferC typed NULL instance … → API: tclmkkernel_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: tclmkkernel_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: tclmkkernel_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: tclmkkernel_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: tclmkkernel_MkBufferC_Create64

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

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

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

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

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

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

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) $buf Delete

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 [$buf Dup]

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

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

Parameters

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

Returns

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

See also

MkObjDup MkBufferDelete

(constructor) MkBufferC [$buf Merge]

top Merge-Constructor - create a new MkBufferC as a merge from an existing object … → API: tclmkkernel_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 [$buf SetBinaryR val:binary]

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

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

Returns

the MkBufferS object

Parameters

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

MkBufferC [$buf SetBUF val:MkBufferC]

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

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

Returns

the MkBufferS object

Parameters

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

MkBufferC [$buf SetStringR val:string]

top Set the MkBufferC to the val … → API: tclmkkernel_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

[$buf SetTT val:int8]

top

The BufferSetTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
	MkBufferC	[$buf SetI8 val:int8]	MkBufferSetI8_RT
	MkBufferC	[$buf SetI16 val:int16]	MkBufferSetI16_RT
	MkBufferC	[$buf SetI32 val:int32]	MkBufferSetI32_RT
	MkBufferC	[$buf SetI64 val:int64]	MkBufferSetI64_RT
	MkBufferC	[$buf SetSTR val:string]	MkBufferSetSTR_RT
	MkBufferC	[$buf SetBIN val:binary]	MkBufferSetBIN_RT
	MkBufferC	[$buf SetBOL val:bool]	MkBufferSetBOL_RT
	MkBufferC	[$buf SetFLT val:float]	MkBufferSetFLT_RT
	MkBufferC	[$buf SetDBL 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 [$buf GetBFL ?val_inout:MkBufferListC="MK_NULL"?]

top function to read an MkBufferListC from an MkBufferC object … → API: tclmkkernel_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 tclmkkernel function and therefore never becomes "MK_NULL" for a non-error result.
    For details on the reference object value, see: MkKernel_Storage_C_API.
• The newly created reference-object is owned by the caller.

Exceptions

MkExceptionC

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

MkBufferC [$buf GetBUF]

top get a val_out from a MkBufferC … → API: tclmkkernel_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 [$buf GetStringR]

top get a val_out from a MkBufferC … → API: tclmkkernel_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.

[$buf GetTT]

top

The BufferGetTT provide a single function for every PRIMITIVE TYPE

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

get a val_out from a MkBufferC …

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

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

Exceptions

MkExceptionC

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

Parameters

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

MkBufferC ACCESS

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

MkBufferC [$buf AppendSTR val:string]

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

Parameters

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

Returns

the MkBufferC object with the new value

Example from server.tcl → read and update a MkBufferC

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

MkBufferC [$buf AppendStringR val:string]

top append a single string to a MkBufferC object … → API: tclmkkernel_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.tcl → read and update a MkBufferC

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

int32 [$buf Pop val:string]

top delete str from the MkBufferC … → API: tclmkkernel_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 [$buf Push val:string]

top add str to the MkBufferC … → API: tclmkkernel_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 [$buf ToObject]

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] [$buf GetType1]

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

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

MkTypeE [$buf GetType2]

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

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

string [$buf GetType3]

top return the type from a MkBufferC as single character string … → API: tclmkkernel_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 [$buf IsLocal]

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

Parameters

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

Returns

a boolean value… yes or no

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

top log the MkBufferC … → API: tclmkkernel_MkObjectC_Log

Parameters

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

See also

MkBufferC

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

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

Parameters

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

MkBufferC MISC

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

$buf CastTo typ:MkTypeE

top change the type of an MkBufferC to type … → API: tclmkkernel_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 [$buf1 Cmp buf2:MkBufferC]

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

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

Parameters

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

Returns

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

MkBufferC [$buf Copy srce:MkBufferC]

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

Parameters

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

Returns

the dest object

MkBufferC [$buf Reset]

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

Parameters

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

See also

$buf ResetFull

$buf ResetFull

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

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

Parameters

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

See also

MkBufferC [$buf Reset]

MkBufferC [$buf SizeAdd size:int32]

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

Parameters

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

Returns

the input buf

MkBufferC [$buf SizeNew size:int32]

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

Returns

the input buf

Parameters

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

MkBufferC [$buf Temp]

top create a temporary copy of the MkBufferC buf … → API: tclmkkernel_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 tclmkkernel 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 [$inst ToString]

top String-Slot - returns the string representation of the inst … → API: tclmkkernel_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 tclmkkernel 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 …
		new	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: tclmkkernel_MkBufferStreamC_HandleResolve

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [$bus HandleGet]

top Handle-Get-Slot - returns a export-hdl to the MkBufferStreamC useable for external storage → API: tclmkkernel_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: tclmkkernel_MkBufferStreamC_Instances

The head-instance is the last instance created.

MkBufferStreamC [$bus Next]

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

MkBufferStreamC [$bus Prev]

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

MkBufferStreamC CLASS MISC

MkBufferStreamC - Misc class functions …

(static) MkBufferStreamC [MkBufferStreamC GetNull]

top Null-Slot - return a MkBufferStreamC typed NULL instance … → API: tclmkkernel_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: tclmkkernel_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: tclmkkernel_MkBufferStreamC_Create64

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

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

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

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

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

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

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

top same as BufferStreamCreate but require no cleanup … → API: tclmkkernel_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.tcl → performance test with TLS storage

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

Parameters

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

Returns

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

Note

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

Attention

for usage of the TLS-storage read more at StorageCreateTLS

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

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

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) $bus Delete

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 [$src Dup]

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

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

Returns

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

See also

MkObjDup MkBufferStreamDelete

(constructor) MkBufferStreamC [$bus Merge]

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

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

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

Parameters

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

Returns

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

Attention

The new instance have to be deleted with BufferStreamDelete

See also

BufferStreamDup BufferStreamResetFull BufferStreamDelete

MkBufferStreamC READ

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

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

MkBufferListC [$bus ReadALL ?val_inout:MkBufferListC="MK_NULL"?]

top get a temporary MkBufferListC from all data in the MkBufferStreamC … → API: tclmkkernel_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 tclmkkernel function and therefore never becomes "MK_NULL" for a non-error result.
    For details on the reference object value, see: MkKernel_Storage_C_API.
• The newly created reference-object is owned by the caller.

Exceptions

MkExceptionC

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

See also

BufferStreamReadBFL

MkBufferListC [$bus ReadBFL]

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

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

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

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

Parameters

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

Exceptions

MkExceptionC

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

See also

BufferStreamReadALL BufferStreamWriteBFL

Attention

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

MkBufferC [$bus ReadBUF]

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

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

Precondition

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

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

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

Exceptions

MkExceptionC

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

Parameters

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

MkTypeE [$bus ReadGetNextType]

top get the type (MkTypeE) of the next Item in the MkBufferStreamC or "0" if not available → API: tclmkkernel_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 [$bus ReadGetNumItems]

top get the number of items left in the MkBufferStreamC … → API: tclmkkernel_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 [$bus ReadItemExists]

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

Parameters

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

Returns

boolean, true or false

$bus ReadL_END

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

$bus ReadL_START ?buf:MkBufferC="MK_NULL"?

top START read a list-item-type from the MkBufferStreamC … → API: tclmkkernel_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 [$bus ReadLONG]

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

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

this api-function is NOT portable

See also

$bus WriteLONG val:long

$bus ReadUndo

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

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

Parameters

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

Exceptions

MkExceptionC

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

[$bus ReadTT]

top

The BufferStreamReadTT provide a single function for every PRIMITIVE TYPE

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

read a val_out from the MkBufferStreamC …

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

Precondition

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

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

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

Exceptions

MkExceptionC

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

Parameters

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

MkBufferStreamC WRITE

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

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

$bus WriteBFL bfl:MkBufferListC

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

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

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

Parameters

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

Exceptions

MkExceptionC

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

See also

BufferStreamWriteL_FLAT BufferStreamReadBFL

$bus WriteBUF val:MkBufferC

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

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

Parameters

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

Exceptions

MkExceptionC

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

$bus WriteBUS_FLAT add:MkBufferStreamC

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

The add is appended to bus

Parameters

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

Exceptions

MkExceptionC

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

$bus WriteHDL val:int32

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

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

The handle support the following API:

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

$bus WriteL_END

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

$bus WriteL_FLAT bfl:MkBufferListC

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

A MkBufferListC can be written into a MkBufferStreamC using:

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

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

Parameters

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

Exceptions

MkExceptionC

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

See also

MkBufferStreamReadBFL

$bus WriteL_START

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

$bus WriteLONG val:long

top write the long native object into the MkBufferStreamC … → API: tclmkkernel_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 [$bus ReadLONG]

$bus WriteTT val:int8

top

The BufferStreamWriteTT provide a single function for every PRIMITIVE TYPE

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

write a PRIMITIVE TYPE into the MkBufferStreamC …

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

Parameters

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

Exceptions

MkExceptionC

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

MkBufferStreamC MISC

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

MkBufferStreamC [$bus Copy src:MkBufferStreamC]

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

Parameters

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

Returns

the bus instance

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

top log the MkBufferStreamC … → API: tclmkkernel_MkObjectC_Log

Parameters

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

$bus PosToStart

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

MkBufferStreamC [$bus Reset]

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

Parameters

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

See also

$bus ResetFull

$bus ResetFull

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

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

Parameters

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

See also

MkBufferStreamC [$bus Reset]

MkBufferListC [$bus ToBFL]

top convert the bus into a MkBufferListC … → API: tclmkkernel_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 tclmkkernel 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 [$inst ToString]

top String-Slot - returns the string representation of the inst … → API: tclmkkernel_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 tclmkkernel 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 …
		new	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?]	tclmkkernel::MkBufferListC new ?num:I=0?
(destructor) $bfl Delete	rename $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: tclmkkernel_MkBufferListC_HandleResolve

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [$bfl HandleGet]

top Handle-Get-Slot - returns a export-hdl to the MkBufferListC useable for external storage → API: tclmkkernel_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: tclmkkernel_MkBufferListC_Instances

The head-instance is the last instance created.

MkBufferListC [$bfl Next]

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

MkBufferListC [$bfl Prev]

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

MkBufferListC CLASS MISC

MkBufferListC - Misc class functions …

(static) MkBufferListC [MkBufferListC GetNull]

top Null-Slot - return a MkBufferListC typed NULL instance … → API: tclmkkernel_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: tclmkkernel_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: tclmkkernel_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: tclmkkernel_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.tcl → performance test with TLS storage

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

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

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

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

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

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

Parameters

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

Returns

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

Attention

for usage of the TLS-storage read more at StorageCreateTLS

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

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

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) $bfl Delete

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 [$bfl Dup]

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

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

Returns

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

See also

MkObjDup

(constructor) MkBufferListC [$bfl Merge]

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

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

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

Parameters

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

Returns

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

Attention

The new instance have to be deleted with BufferListDelete

See also

BufferListDup

MkBufferListC APPEND

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

$bfl AppendBUF val:MkBufferC

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

Parameters

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

Attention

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

$bfl AppendG val:long

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

Parameters

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

MkBufferListC [$bfl AppendLA 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: tclmkkernel_MkBufferListC_AppendLA

Parameters

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

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

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

Parameters

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

Attention

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

$bfl AppendStringR val:string

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

Parameters

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

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

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

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

Parameters

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

Attention

After append the object addBuf will be owned by bfl.

$bfl AppendTT val:int8

top

The BufferListAppendTT provide a single function for every PRIMITIVE TYPE

attribute	return	command	C-API :
		$bfl AppendI8 val:int8	MkBufferListAppendI8_RT
		$bfl AppendI16 val:int16	MkBufferListAppendI16_RT
		$bfl AppendI32 val:int32	MkBufferListAppendI32_RT
		$bfl AppendI64 val:int64	MkBufferListAppendI64_RT
		$bfl AppendSTR val:string	MkBufferListAppendSTR_RT
		$bfl AppendBIN val:binary	MkBufferListAppendBIN_RT
		$bfl AppendBOL val:bool	MkBufferListAppendBOL_RT
		$bfl AppendFLT val:float	MkBufferListAppendFLT_RT
		$bfl AppendDBL 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 [$bfl CheckOption opt:string ?onlyFirst:bool=false?]

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

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

Parameters

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

MkBufferC [$bfl CheckOptionBUF opt:string ?defval:MkBufferC="MK_NULL"? ?onlyFirst:bool=true?]

top search for opt in MkBufferListS list and fill var with opt_argument or the defval value … → API: tclmkkernel_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 tclmkkernel function and therefore never becomes "MK_NULL" for a non-error result.
  For details on the out/return value, see: MkKernel_Storage_C_API.

[$bfl CheckOptionTT 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	[$bfl CheckOptionI8 opt:string ?defval:int8=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionI8_RT
	int16	[$bfl CheckOptionI16 opt:string ?defval:int16=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionI16_RT
	int32	[$bfl CheckOptionI32 opt:string ?defval:int32=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionI32_RT
	int64	[$bfl CheckOptionI64 opt:string ?defval:int64=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionI64_RT
	string	[$bfl CheckOptionSTR opt:string ?defval:string=""? ?onlyFirst:bool=true?]	MkBufferListCheckOptionSTR_RT
	bool	[$bfl CheckOptionBOL opt:string ?defval:bool=false? ?onlyFirst:bool=true?]	MkBufferListCheckOptionBOL_RT
	float	[$bfl CheckOptionFLT opt:string ?defval:float=0? ?onlyFirst:bool=true?]	MkBufferListCheckOptionFLT_RT
	double	[$bfl CheckOptionDBL 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 …

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

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

Parameters

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

Exceptions

MkExceptionC

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

MkBufferC [$bfl IndexGet index:int32]

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

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

See also

BufferListIndexGetBUF

MkBufferC [$bfl IndexGetBUF index:int32]

top get the index element from MkBufferListC ... if not available… create it. … → API: tclmkkernel_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 [$bfl IndexGetSTR index:int32]

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

for details please refer to BufferListIndexGetBUF.

Parameters

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

Returns

the string requested or an EMPTY-STRING on error

$bfl IndexSet index:int32 buf:MkBufferC

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

Parameters

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

Exceptions

MkExceptionC

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

Attention

It is an error if index is not available.

See also

BufferListIndexSetBUF

$bfl IndexSetBUF index:int32 buf:MkBufferC

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

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

Parameters

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

$bfl IndexSetSTR index:int32 str:string

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

for details please refer to BufferListIndexGetBUF

Parameters

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

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

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

If the index is not available, this is an error

Parameters

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

Exceptions

MkExceptionC

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

Attention

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

See also

BufferListDelete

MkBufferListC LOG

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

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

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

Parameters

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

See also

MkBufferListC

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

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

Parameters

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

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

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

Parameters

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

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

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

Parameters

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

MkBufferListC MISC

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

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

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

$to Move from:MkBufferListC

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

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

Parameters

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

$bfl Copy src:MkBufferListC

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

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

Parameters

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

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

top merge a MkBufferListS list into an MkBufferListS object on position … → API: tclmkkernel_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 [$bfl Cmp bfl2:MkBufferListC]

top compare two buffer-list … → API: tclmkkernel_MkBufferListC_Cmp

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

Parameters

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

Returns

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

$bfl Reserve num:int32

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

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

Parameters

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

MkBufferListC [$bfl Reset]

top reset a MkBufferListC object … → API: tclmkkernel_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 [$bfl SearchC str:string ?len:int32=-1? ?startindex:int32=0?]

top search MK_STR item from a MkBufferListS object starting at startindex … → API: tclmkkernel_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 [$bfl Size]

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

Parameters

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

Returns

the number-of-items in the bfl

MkBufferListC [$bfl Sort]

top sort a MkBufferListC … → API: tclmkkernel_MkBufferListC_Sort

Parameters

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

Returns

Return the input bfl as sorted list

MkBufferC [$bfl ToBuffer]

top Export a bfl into an MkBufferC using an MkBufferStreamC … → API: tclmkkernel_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 tclmkkernel 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...] [$bfl ToList]

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 [$bfl ToString]

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

Parameters

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

Returns

the required string

Attention

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

---

MkErrorC

MkErrorC CLASS
		Export	MkErrorC - Export class functions …
		Introspection	MkErrorC - Introspection class functions …
		Misc	MkErrorC - Misc class functions …
MkErrorC TOR
		Delete	Destructor - delete a MkErrorS object …
		Dup	Dup-Constructor - create a new MkErrorC instance as copy from an existing MkErrorC instance …
MkErrorC GET
		GetCode	get the value of MkErrorS::code …
		GetNum	get the MkErrorS::num. The number can be used as exit-code …
		GetSize	get the error-message-size from the exception-object …
		GetText	get the MkErrorS::text …
MkErrorC RAISE
		PanicC	do a panic with string as argument …
		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 tclmkkernel 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 tclmkkernel 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 tclmkkernel into the error-handling-code of the target Tcl.

Example from Filter6.tcl → use MqContextErrorCatch to convert a Tcl error into a tclmkkernel error

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

MkExceptionC

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

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

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

• The default-error is defined in MkRuntimeS::error_mk.
• On error the default-error is set to the error-data, the MkErrorE status change to 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   [my ReadBUF]
        set cl    [Client new]
        $cl myLinkCreate [my ConfigGetStartAs]
        $cl Send "W" "GPID@I" PID
        my SysKill $PID 9
        set RET 0
        foreach num {1 2 3} {
          try {
            set RET [$cl Send "W" "ECOI:U@I" $VAL]
          } trap {MkExceptionC} "" {
            set err [$cl ErrorCatch]
            if {[$err IsSOCKET]} {
              $err Reset
              $cl LinkConnect
              continue
            } else {
              $err Raise
            }
            $err Delete
          }
          break
        }
        my SendSTART
        my SendI32 $RET

Returns

the result of the check, true or false

Parameters

[in]

exception

the exception object from Tcl, 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: tclmkkernel_MkErrorC_HandleResolve

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [$err HandleGet]

top Handle-Get-Slot - returns a export-hdl to the MkErrorC useable for external storage → API: tclmkkernel_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: tclmkkernel_MkErrorC_Instances

The head-instance is the last instance created.

MkErrorC [$err Next]

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

MkErrorC [$err Prev]

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

MkErrorC CLASS MISC

MkErrorC - Misc class functions …

(static) MkErrorC [MkErrorC GetNull]

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

MkErrorC TOR

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

(destructor) $err Delete

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

There are two different ways to delete an instance:

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

Attention

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

See also

BufferDup ObjectDelete

(constructor) MkErrorC [$srce Dup]

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

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

Returns

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

See also

MkObjDup MkErrorDelete

MkErrorC GET

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

MkErrorE [$err GetCode]

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

int32 [$err GetNum]

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

long [$err GetSize]

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

string [$err GetText]

top get the MkErrorS::text … → API: tclmkkernel_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 errfmt:MkObjectC callfunc:string errnum:int32 message:string

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errfmt	a managed object used to identify and format the error-message
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	errnum	the error number used as exit-code as well
	message	the string to be displayed

Attention

this function will never return

$err AppendC message:string

top append the message to the MkErrorS::text … → API: tclmkkernel_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 [$err NoRaise]

top ignore the next return of MK_ERROR and do not raise an target-language-exception … → API: tclmkkernel_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.tcl → create and send an background-error message

  method bgError {} {
    set master [my SlaveGetMaster]
    if {$master ne ""} {
      set err [[$master ErrorFORMAT] NoRaise]
      $err SetC [$err GetText] "BGERROR" [$err GetNum]
      $master SendERROR
    }
  }

Parameters

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

Returns

the input err with MkErrorS::noRaise flag set

$err Raise

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

If ther is no tclmkkernel-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_tcl_ErrorCatch "ErrorCatch" \ref doc_mk_tcl_ErrorReset "ErrorReset"

$err SetC message:string ?callfunc:string="MK_NULL"? ?errnum:int32=-1?

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

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed) - err==NULL allowed
[in]	message	the string to be displayed as message
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	errnum	the error number used as exit-code as well

Attention

Use ErrorNoRaise to avoid raise an error.

MkErrorC SIGNAL

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

bool [$err IsABORT]

top check on ABORT signal … → API: tclmkkernel_MkErrorC_IsABORT

bool [$err IsEXIT]

top check on APPLICATION-EXIT error … → API: tclmkkernel_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/tcl/Filter4.tcl 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 [$err IsSOCKET]

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

bool [$err IsTIMEOUT]

top check on TIMEOUT error … → API: tclmkkernel_MkErrorC_IsTIMEOUT

$err SetABORT ?detail:string="UNKNOWN"? ?callfunc:string="MK_NULL"?

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

The ABORT-signal is used to disrupt the current execution like an error and unwind the calling stack. The MkErrorIsABORT is used to detect the ABORT-signal and MkErrorReset is used to clear the ABORT-signal

$err SetCode code:MkErrorE

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

$err SetCONTINUE

top signal end of processing in an MqMqEventIF callback … → API: tclmkkernel_MkErrorC_SetCONTINUE

$err SetEXIT ?callfunc:string="MK_NULL"?

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

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

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

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

$err SetSOCKET ?detail:string="UNKNOWN"? ?callfunc:string="MK_NULL"?

top create SOCKET-DOWN error … → API: tclmkkernel_MkErrorC_SetSOCKET

MkErrorC SYSTEM

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

(static) MkErrorC [MkErrorC DEFAULT]

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

The default-error is defined once per runtime and is used as only-valid-source of an MkErrorC in a thread or process.

See also

ErrorFORMAT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

(static) MkErrorC [MkErrorC FORMAT ?fmtobj:MkObjectC="MK_NULL"?]

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

Returns

the MkErrorS::format_of_error or MkErrorS::source_of_error attribute

MkErrorFORMAT - usage

Set the MkErrorS::format_of_error attribute to fmtobj or "MK_NULL". The next error-message will be formated as usual and than be raised as error. The default-error will be modified.

The next error-message created with ErrorSetC etc is formatted with MkRuntimeS->cid ("context-in-duty") or simply as "DEFAULT" if cid == NULL.

Parameters

[in]

fmtobj

managed object used to format the log-message (default="MK_NULL" → use default-format)

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

(static) MkErrorC [MkErrorC IGNORE]

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

The next error will be ignored, no formatting will be performed and the the default-error will not be modified.

MkErrorIGNORE - usage

There are two functions to suppress an error: MkErrorIGNORE and MkErrorNoRaise.

MkErrorIGNORE

Set the MkErrorS::format_of_error attribute to IGNORE. The next error will be ignored, no formatting will be performed and the the default-error will not be modified.

MkErrorNoRaise

Set the MkErrorS::noRaise attribute to TRUE. The next error will be set as usual but not raised. This is usefull to set an error and later append additional information to the error. Final the error have to be raised with MkErrorRaise.

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

(static) MkErrorC [MkErrorC PRINT]

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

The next error-message will be formated as usual and than be reported using MkLogVL. The default-error will not be modified.

MkErrorPRINT - usage

Set the MkErrorS::format_of_error attribute to PRINT.

Returns

the default-error with MkErrorS::format_of_error attribute set

See also

ErrorDEFAULT, ErrorPRINT, ErrorIGNORE, MkErrorPANIC

MkErrorC MISC

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

MkErrorC [$err Catch ?exception:errorCode="MK_NULL"? ?callfunc:string="MK_NULL"?]

top convert a programming-language-error into an tclmkkernel error … → API: tclmkkernel_MkErrorC_Catch

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

Example from Bug3.tcl → catch an error using MkErrorC [$err Catch ?exception:errorCode="MK_NULL"? ?callfunc:string="MK_NULL"?]

  } on error {} {
    [ [MkErrorC DEFAULT] Catch ] Println
  }

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 Tcl, if "MK_NULL" the global exception object is used
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)

Returns

the ErrorDEFAULT initialized with exception value

See also

ObjectErrorCatch ErrorRaise ErrorReset

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

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

Parameters

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

See also

MkErrorC $err Log ?fmtobj:MkObjectC="MK_NULL"? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?

$err Println

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

Parameters

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

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

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

Attention

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

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

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

See also

ErrorRaise ErrorCatch

MkErrorE [$err Stack ?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: tclmkkernel_MkErrorC_Stack

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed) → "MK_NULL" allowed
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	callfile	the name of the file the call take place (e.g. FILE)
[in]	callline	the number of the line the call take place (e.g. LINE)

Exceptions

MkExceptionC

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

$err StackFormat ?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: tclmkkernel_MkErrorC_StackFormat

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	err	the MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]	callfile	the name of the file the call take place (e.g. FILE)
[in]	callline	the number of the line the call take place (e.g. LINE)

string [$inst ToString]

top String-Slot - returns the string representation of the inst … → API: tclmkkernel_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 tclmkkernel 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 …
		new	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 RuntimeSetLogfile or using the class MkLogFileC.

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

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

possible values are:

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

MkLogFileC CLASS

NAVI: top, up

MkLogFileC CLASS EXPORT

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

MkLogFileC CLASS INTROSPECTION

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

MkLogFileC CLASS MISC

GetNull

Null-Slot - return a MkLogFileC typed NULL instance …

MkLogFileC CLASS DETAILS

C-API: MkLogFileC_Class_C_API - MkLogFileC - define the class …

MkLogFileC CLASS EXPORT

MkLogFileC - Export class functions …

(static) MkLogFileC [MkLogFileC HandleResolve netHdl:MK_HDL]

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

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

Parameters

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

Returns

the required handle or "MK_NULL" if netHdl is invalid

MK_HDL [$lfl HandleGet]

top Handle-Get-Slot - returns a export-hdl to the MkLogFileC useable for external storage → API: tclmkkernel_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: tclmkkernel_MkLogFileC_Instances

The head-instance is the last instance created.

MkLogFileC [$lfl Next]

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

MkLogFileC [$lfl Prev]

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

MkLogFileC CLASS MISC

MkLogFileC - Misc class functions …

(static) MkLogFileC [MkLogFileC GetNull]

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

MkLogFileC TOR

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

(constructor,static) MkLogFileC [MkLogFileC Open errfmt:MkObjectC file:string]

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

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errfmt	a managed object used to identify and format the error-message
[in]	file	the filename to open
[out]	lfh_out	returns

Returns

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

Exceptions

MkExceptionC

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

Attention

on error the lfh_out is set to "MK_NULL"

(constructor,static) MkLogFileC [MkLogFileC new errfmt:MkObjectC file:string]

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

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

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	errfmt	a managed object used to identify and format the error-message
[in]	file	the filename to open
[out]	lfh_out	returns

Returns

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

Exceptions

MkExceptionC

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

Attention

on error the lfh_out is set to "MK_NULL"

(destructor) $lfh Close

top Destructor - delete a MkLogFileC instance … → API: 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 [$lfl GetFile]

top get the log-file … → API: tclmkkernel_MkLogFileC_GetFile

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	lfl	the MkLogFileS instance to work on
[out]	file_out	the log-file to return

Exceptions

MkExceptionC

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

$lfl WriteC text:string

top write to log-file … → API: tclmkkernel_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
		GetDebug	get the MkRuntimeS::debug value …
		GetErrorCode	return MkErrorS::code from a given MkRuntimeC …
		GetIsSilent	get the MkRuntimeS::isSilent value …
		GetLogfile	get the MkRuntimeS::logfile value …
		SetDebug	set the MkRuntimeS::debug value …
		SetIsSilent	set the MkRuntimeS::isSilent value …
		SetLogfile	set the MkRuntimeS::logfile value and cleanup old value …
MkRuntimeC INFO
		Log	log the MkRuntimeC …

MkRuntimeC DETAIL

C-API: MkRuntimeC_C_API - MkRuntimeC - The class known as mkrt or runtime is the main tclmkkernel 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 tclmkkernel 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_tcl_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 GetDebug]

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

(static) MkErrorE [MkRuntimeC GetErrorCode]

top return MkErrorS::code from a given MkRuntimeC … → API: tclmkkernel_MkRuntimeC_GetErrorCode

(static) bool [MkRuntimeC GetIsSilent]

top get the MkRuntimeS::isSilent value … → API: tclmkkernel_MkRuntimeC_GetIsSilent

(static) string [MkRuntimeC GetLogfile]

top get the MkRuntimeS::logfile value … → API: tclmkkernel_MkRuntimeC_GetLogfile

Attention

the string is owned by tclmkkernel -> do not free !!

(static) MkRuntimeC SetDebug dbg:int32

top set the MkRuntimeS::debug value … → API: tclmkkernel_MkRuntimeC_SetDebug

(static) MkRuntimeC SetIsSilent silent:bool

top set the MkRuntimeS::isSilent value … → API: tclmkkernel_MkRuntimeC_SetIsSilent

(static) MkRuntimeC SetLogfile logfile:string

top set the MkRuntimeS::logfile value and cleanup old value … → API: tclmkkernel_MkRuntimeC_SetLogfile

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	logfile	filename, "stdout" or "stderr", default = "stderr" for "MK_NULL" or ""

MkRuntimeC INFO

C-API: MkRuntimeC_Info_C_API - MkRuntimeC - various functions to print information about the rt …

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

top log the MkRuntimeC … → API: tclmkkernel_MkObjectC_Log

Parameters

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

See also

MkRuntimeC

---

BINARY OBJECT

No special binary-object is used. All binary-data is available as Tcl binary.

---

EXAMPLES

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

  method Ot_BUF2 {} {
    my SendSTART

    foreach i {1 2 3} {
      set buf [my ReadBUF]
      my SendSTR [$buf GetType1]
      my SendBUF $buf
      $buf Delete
    }

    my SendRETURN
  }

---

SEE ALSO

libmkkernel, ccmkkernel, csmkkernel, javamkkernel, gomkkernel, pymkkernel, rbmkkernel, tclmkkernel, perlmkkernel, phpmkkernel

KEYWORDS

Tcl, unix, socket, message, msgque