rbmkkernel

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

SYNOPSIS

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

• require 'rbmkkernel' 

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

object	description
MkKernel	the namespace with all rbmkkernel specific definitions
MkKernel.Attribute	the interface to access the package specific attribute
MkKernel::LcClassC.Attribute	the interface to access the class specific attribute
Instance.Attribute	the interface to access the instance specific attribute

To access all features without MkKernel prefix use:

• include MkKernel 

Using the rbmkkernel package ...

PYTHON package libraries

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

librbmkkernel.la

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

rbmkkernel.so

ruby loadable module file.

rbmkkernel.la

ruby loadable module libtool file.

> man ruby

To access the rbmkkernel package the environment variable RUBYLIB have to include the directory.

RUBYLIB
      A colon-separated list of directories that are added to Ruby's library load path ("$:"). 
      Directories from this environment variable are searched before the standard load path is searched.

      e.g.:
        RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"

---

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 rbmkkernel 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 Ruby programmer. !!

PACKAGE

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

The rbmkkernel package is loaded with:

‍

require 'rbmkkernel' 

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

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

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

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

  def BFL2()
    tmp1 = ReadBFL()                              ; # "tmp1" is now a reference to the FLS storage of "ReadBFL"
    tmp2 = ReadBFL()                              ; # ERROR: the "tmp2" is using a SHARED reference with "tmp1"
    Send("R","LL",tmp1,tmp2)                      ; # ERROR: "tmp1" and "tmp2" are the SAME values
  end

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

  def pBFL3()
    tmp2 = ReadBFL()                              ; # ERROR: the "tmp2" is using a SHARED reference with "tmp1"
  end
  def BFL3()
    tmp1 = ReadBFL()                              ; # "tmp1" is now a reference to the FLS storage of "ReadBFL"
    Send("C",method(:pBFL3),"ECOL:[III]",4,5,6)   ; # ATTENTION: callback "pBFL3" using "ReadBFL"
    ProcessEvent(MqWaitOnEventE::OWN)             ; # ERROR: enter event-loop, callback "pBFL3" is called
    Send("R","L",tmp1)                            ; # ERROR: "tmp1" has now the value from "tmp2"
  end

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

  def BFL4()
    tmp1 = ReadBFL()                              ; # "tmp1" is now a reference to the FLS storage of "ReadBFL"
    glb1 = tmp1.Dup()                             ; # OK: "glb1" is now a UNSHARED reference to the global memory
    tmp2 = ReadBFL()                              ; # "tmp2" is now a reference to the FLS storage of "ReadBFL"
    Send("R","LL",glb1,tmp2)                      ; # OK: "glb1" (alias tmp1) and "tmp2" are separate references
    glb1.Delete()                                 ; # with "garbage-collection" the global memory does not have to be released
  end

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.rb → performance test with TLS storage in a local (controlled) context

  def BUST
    bus = MkBufferStreamC.CreateTLS( "perfserver-BUST" )
    while ReadItemExists()
      bus.WriteBUF(ReadBUF())
    end
    bus.PosToStart()
    SendSTART()
    while bus.ReadItemExists()
      SendBUF(bus.ReadBUF())
    end
    SendRETURN()
  end

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

‍

require 'rbmkkernel' 

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

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

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

MkKernel SETUP DETAILS

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

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

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

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

(static) MkErrorE MkKernel.ErrorE_FromInt(value:int32)

top return the MkErrorE from integer … → API: rbmkkernel_MkKernel_ErrorE_FromInt

(static) int32 MkKernel.ErrorE_ToInt(value:MkErrorE)

top return the MkErrorE as integer … → API: rbmkkernel_MkKernel_ErrorE_ToInt

(static) string MkKernel.ErrorE_ToString(value:MkErrorE)

top return the MkErrorE as string … → API: rbmkkernel_MkKernel_ErrorE_ToString

enum MkIdSE

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

(static) MkIdSE MkKernel.IdSE_FromInt(value:int32)

top return the MkIdSE from integer … → API: rbmkkernel_MkKernel_IdSE_FromInt

(static) int32 MkKernel.IdSE_ToInt(value:MkIdSE)

top return the MkIdSE as integer … → API: rbmkkernel_MkKernel_IdSE_ToInt

(static) string MkKernel.IdSE_ToString(value:MkIdSE)

top return the MkIdSE as string … → API: rbmkkernel_MkKernel_IdSE_ToString

enum MkTimeoutE

top Predefined Timeout values … → API: rbmkkernel_MkTimeoutE

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

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

(static) MkTimeoutE MkKernel.TimeoutE_FromInt(value:int32)

top return the MkTimeoutE from integer … → API: rbmkkernel_MkKernel_TimeoutE_FromInt

(static) int32 MkKernel.TimeoutE_ToInt(value:MkTimeoutE)

top return the MkTimeoutE as integer … → API: rbmkkernel_MkKernel_TimeoutE_ToInt

(static) string MkKernel.TimeoutE_ToString(value:MkTimeoutE)

top return the MkTimeoutE as string … → API: rbmkkernel_MkKernel_TimeoutE_ToString

enum MkTypeE

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

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

See also

MkTypeE_ToString, MkTypeE_ToInt, MkTypeE_FromInt, BufferGetType2, BufferCastTo, BufferStreamReadGetNextType

(static) MkTypeE MkKernel.TypeE_FromInt(value:int32)

top return the MkTypeE from integer … → API: rbmkkernel_MkKernel_TypeE_FromInt

(static) int32 MkKernel.TypeE_ToInt(value:MkTypeE)

top return the MkTypeE as integer … → API: rbmkkernel_MkKernel_TypeE_ToInt

(static) string MkKernel.TypeE_ToString(value:MkTypeE)

top return the MkTypeE as string … → API: rbmkkernel_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-Ruby-Instance and the rbmkkernel-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 rbmkkernel error …
		IsNull	ckeck if the object is nil
		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 Ruby-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 …

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

(static) MkObjectC MkObjectC.HandleResolve(netHdl:MK_HDL)

top Handle-Resolve-Slot - return a MkObjectC from netHdl or nil if invalid… → API: rbmkkernel_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 nil if netHdl is invalid

netObj.HandleDelete()

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

bool obj.HandleExists()

top check if obj has already a handle defined… → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_MkObjectC_Instances

The head-instance is the last instance created.

MkObjectC obj.Next()

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

MkObjectC obj.Prev()

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

MkObjectC CLASS MISC

MkObjectC - Misc class functions …

(static) MkObjectC MkObjectC.GetNull()

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

See also

MkObjectDeleteCallbackSetup

(static) MkObjectC.DeleteCallbackSetup(ident:string, ?callback:callable=nil?, ?filter:string="nil"?)

top Create/Delete the instance-delete-callback … → API: rbmkkernel_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 nil than the callback with name ident is deleted if exists and no new callback is created.
• If nil 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 nil 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 nil and not "".
[in]	fCall	(C-Only) Internal required: the callback, if nil 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: rbmkkernel_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-Ruby-Instance and the rbmkkernel-Instance. → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_MkObjectC_DbgLogC

obj.DbgO(?callfunc:string="MK_NULL"?)

top debug: write the object-details to MkLogFileC (default: stderr) … → API: rbmkkernel_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 (nil 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: rbmkkernel_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=nil → 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: rbmkkernel_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=nil → 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: rbmkkernel_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=nil → 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=nil?, ?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: rbmkkernel_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=nil → 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=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)

top log the MkObjectS verbose into the MkLogFileC (default: stderr) … → API: rbmkkernel_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=nil → 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=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)

obj.LogSimple(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)

top log the MkObjectS into the MkLogFileC (default: stderr) … → API: rbmkkernel_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=nil → 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=nil?, ?callfunc:string="MK_NULL"?)

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

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

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

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

        @cl[id].SendSTART()
        begin
          ProxyItem(@cl[id])
          @cl[id].SendEND_AND_WAIT("ECOI", 5)
        rescue Exception => ex
          err = ErrorCatch(ex)
          SendI32(err.GetNum())
          SendSTR(err.GetText())
          err.Reset()
        end

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 Ruby, if nil 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 nil → API: rbmkkernel_MkObjectC_IsNull

MkErrorC obj.ToError()

top Error-Slot - return an error-object pre initialized with obj data. → API: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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 Ruby-Class-Name of the obj as string → API: rbmkkernel_MkObjectC_ToNameOfClass

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

ObjectToNameOfType	returns the name of the rbmkkernel type
ObjectToNameOfClass	returns the name of the Ruby class

string obj.ToNameOfType()

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

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

ObjectToNameOfType	returns the name of the libmsgque type
ObjectToNameOfClass	returns the name of the Ruby 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: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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 rbmkkernel is working on data… rbmkkernel 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?)	MkKernel.MkBufferC(?size:long=0?)
(destructor) buf.Delete()	buf = nil

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

  def BUF2
    SendSTART()
    for i in 1..3 do
      buf = ReadBUF()
      SendSTR(buf.GetType1())
      SendBUF(buf)
    end
    SendRETURN()
  end

See also

BufferGetType1 BufferGetType2 BufferGetType3

MkBufferC CLASS

NAVI: top, up

MkBufferC CLASS EXPORT

		HandleResolve	Handle-Resolve-Slot - return a MkBufferC from netHdl or nil 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 nil if invalid… → API: rbmkkernel_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 nil if netHdl is invalid

MK_HDL buf.HandleGet()

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

The head-instance is the last instance created.

MkBufferC buf.Next()

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

MkBufferC buf.Prev()

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

MkBufferC CLASS MISC

MkBufferC - Misc class functions …

(static) MkBufferC MkBufferC.GetNull()

top Null-Slot - return a MkBufferC typed NULL instance … → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 nil or "" than a nil 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: rbmkkernel_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: rbmkkernel_MkBufferC_Create64

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

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

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

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

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

top Constructor - create a new MkBufferC with minimum size of internal storage … → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 nil 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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=nil?)

top function to read an MkBufferListC from an MkBufferC object … → API: rbmkkernel_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 nil at error

• The reference object have to be non nil.
• If reference object is a refrence to a non nil object than the reference object is populated with the result.
• If reference object is a refrence to a nil 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 rbmkkernel function and therefore never becomes nil 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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.rb → read and update a MkBufferC

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

MkBufferC buf.AppendStringR(val:string)

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

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

int32 buf.Pop(val:string)

top delete str from the MkBufferC … → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)

top log the MkBufferC … → API: rbmkkernel_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=nil → 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=nil?, ?callfunc:string="MK_NULL"?)

top log the short MkBufferC object data to the MkLogFileC (default: stderr) … → API: rbmkkernel_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=nil → 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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 nil 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 nil if invalid… → API: rbmkkernel_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 nil if netHdl is invalid

MK_HDL bus.HandleGet()

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

The head-instance is the last instance created.

MkBufferStreamC bus.Next()

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

MkBufferStreamC bus.Prev()

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

MkBufferStreamC CLASS MISC

MkBufferStreamC - Misc class functions …

(static) MkBufferStreamC MkBufferStreamC.GetNull()

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

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

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

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

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

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

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

(static) MkBufferStreamC MkBufferStreamC.CreateTLS(tlsName:string, ?resetB:bool=true?)

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

  def BUST
    bus = MkBufferStreamC.CreateTLS( "perfserver-BUST" )
    while ReadItemExists()
      bus.WriteBUF(ReadBUF())
    end
    bus.PosToStart()
    SendSTART()
    while bus.ReadItemExists()
      SendBUF(bus.ReadBUF())
    end
    SendRETURN()
  end

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 nil or "" than a nil 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 nil 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=nil?)

top get a temporary MkBufferListC from all data in the MkBufferStreamC … → API: rbmkkernel_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 nil at error

• The reference object have to be non nil.
• If reference object is a refrence to a non nil object than the reference object is populated with the result.
• If reference object is a refrence to a nil 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 rbmkkernel function and therefore never becomes nil 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: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_MkBufferStreamC_ReadL_END

bus.ReadL_START(?buf:MkBufferC=nil?)

top START read a list-item-type from the MkBufferStreamC … → API: rbmkkernel_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	nil 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_MkBufferStreamC_WriteL_END

bus.WriteL_FLAT(bfl:MkBufferListC)

top write a MkBufferListC FLAT into the MkBufferStreamC … → API: rbmkkernel_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: rbmkkernel_MkBufferStreamC_WriteL_START

bus.WriteLONG(val:long)

top write the long native object into the MkBufferStreamC … → API: rbmkkernel_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: rbmkkernel_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=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)

top log the MkBufferStreamC … → API: rbmkkernel_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=nil → 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: rbmkkernel_MkBufferStreamC_PosToStart

MkBufferStreamC bus.Reset()

top reset a MkBufferStreamC to the length zero … → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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?)	MkKernel.MkBufferListC(?num:int=0?)
(destructor) bfl.Delete()	bfl = nil

MkBufferListC CLASS

NAVI: top, up

MkBufferListC CLASS EXPORT

		HandleResolve	Handle-Resolve-Slot - return a MkBufferListC from netHdl or nil 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 nil if invalid… → API: rbmkkernel_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 nil if netHdl is invalid

MK_HDL bfl.HandleGet()

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

The head-instance is the last instance created.

MkBufferListC bfl.Next()

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

MkBufferListC bfl.Prev()

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

MkBufferListC CLASS MISC

MkBufferListC - Misc class functions …

(static) MkBufferListC MkBufferListC.GetNull()

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

  def BFLT
    bfl = MkBufferListC.CreateTLS( "perfserver-BFLT" )
    while ReadItemExists()
      bfl.AppendBUF(ReadBUF())
    end
    SendSTART()
    for i in 0...bfl.Size()
      SendBUF(bfl.IndexGet(i))
    end
    SendRETURN()
  end

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 nil or "" than a nil 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 nil 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 nil
[in]	opt	Find opt string in the MkBufferListC
[in]	onlyFirst	Stop after first item was found

MkBufferC bfl.CheckOptionBUF(opt:string, ?defval:MkBufferC=nil?, ?onlyFirst:bool=true?)

top search for opt in MkBufferListS list and fill var with opt_argument or the defval value … → API: rbmkkernel_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 nil
[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 nil 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 nil than an empty MkBufferC is returned.
• (do not free) The memory of the out/return value belongs to the called rbmkkernel function and therefore never becomes nil 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 nil
[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 nil 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: rbmkkernel_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: rbmkkernel_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 nil 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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 nil first.

See also

BufferListDelete

MkBufferListC LOG

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

bfl.Log(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)

top write the detail-summary of the MkBufferListC to MkLogFileC (default: stderr) … → API: rbmkkernel_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=nil → 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=nil?, ?callfunc:string="MK_NULL"?)

top write the short-summary of the MkBufferListC to MkLogFileC (default: stderr) … → API: rbmkkernel_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=nil → 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=nil?, ?callfunc:string="MK_NULL"?)

top write the very-short-summary of the MkBufferListC to MkLogFileC (default: stderr) … → API: rbmkkernel_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=nil → 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=nil?, ?callfunc:string="MK_NULL"?)

top write the very-very-short-summary of the MkBufferListC to MkLogFileC (default: stderr) … → API: rbmkkernel_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=nil → 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: rbmkkernel_MkBufferListC_FileGlob

to.Move(from:MkBufferListC)

top move all internal data from from to the end of to … → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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 nil on error

Attention

(do not free) The memory of the out/return value belongs to the called rbmkkernel function and therefore never becomes nil 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: rbmkkernel_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 rbmkkernel 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 rbmkkernel 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 rbmkkernel into the error-handling-code of the target Ruby.

Example from Filter6.rb → use MqContextErrorCatch to convert a Ruby error into a rbmkkernel error

srv = MqFactoryC.Add(Filter6).New()
begin
  srv.LinkCreate(ARGV)
  srv.ProcessEvent(MqWaitOnEventE::FOREVER)
rescue Exception => ex
  srv.ErrorCatch(ex)
ensure
  srv.Exit()
end

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

        val = ReadBUF()
        cl = Client.new
        cl.LinkCreate(ConfigGetStartAs())
        pid = cl.Send("W", "GPID@I")
        SysKill(pid, 9)
        for i in 1..3
          begin
            ret = cl.Send("W", "ECOI:U@I", val)
          rescue MkExceptionC => ex
            err = ErrorCatch(ex)
            if err.IsSOCKET()
              err.Reset()
              cl.LinkConnect()
              next
            else
              err.Raise()
            end
          end
          break
        end
        SendSTART()
        SendI32(ret)

Returns

the result of the check, true or false

Parameters

[in]

exception

the exception object from Ruby, if nil the global exception object is used

MkErrorC CLASS

NAVI: top, up

MkErrorC CLASS EXPORT

		HandleResolve	Handle-Resolve-Slot - return a MkErrorC from netHdl or nil 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 nil if invalid… → API: rbmkkernel_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 nil if netHdl is invalid

MK_HDL err.HandleGet()

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

The head-instance is the last instance created.

MkErrorC err.Next()

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

MkErrorC err.Prev()

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

MkErrorC CLASS MISC

MkErrorC - Misc class functions …

(static) MkErrorC MkErrorC.GetNull()

top Null-Slot - return a MkErrorC typed NULL instance … → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_MkErrorC_GetCode

int32 err.GetNum()

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

long err.GetSize()

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

string err.GetText()

top get the MkErrorS::text … → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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.rb → create and send an background-error message

  def BgError
    master = SlaveGetMaster()
    if master != nil
      err = master.ErrorFORMAT().NoRaise()
      err.SetC(err.GetText(), "BGERROR", err.GetNum())
      master.SendERROR()
    end
  end

Parameters

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

Returns

the input err with MkErrorS::noRaise flag set

err.Raise()

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

If ther is no rbmkkernel-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_rb_ErrorCatch "ErrorCatch" \ref doc_mk_rb_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: rbmkkernel_MkErrorC_SetC

The message will be formatted into a rbmkkernel 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: rbmkkernel_MkErrorC_IsABORT

bool err.IsEXIT()

top check on APPLICATION-EXIT error … → API: rbmkkernel_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/rb/Filter4.rb 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: rbmkkernel_MkErrorC_IsSOCKET

bool err.IsTIMEOUT()

top check on TIMEOUT error … → API: rbmkkernel_MkErrorC_IsTIMEOUT

err.SetABORT(?detail:string="UNKNOWN"?, ?callfunc:string="MK_NULL"?)

top send the ABORT signal to the calling stack… → API: rbmkkernel_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: rbmkkernel_MkErrorC_SetCode

err.SetCONTINUE()

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

err.SetEXIT(?callfunc:string="MK_NULL"?)

top finish the current callback, return to toplevel and MqExit the application … → API: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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=nil?)

top system-error-format - format and return the default-error … → API: rbmkkernel_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 nil. 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=nil → 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: rbmkkernel_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: rbmkkernel_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=nil?, ?callfunc:string="MK_NULL"?)

top convert a programming-language-error into an rbmkkernel error … → API: rbmkkernel_MkErrorC_Catch

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

Example from Bug3.rb → catch an error using MkErrorC err.Catch(?exception:errorCode=nil?, ?callfunc:string="MK_NULL"?)

rescue Exception => ex
  MkErrorC::DEFAULT().Catch(ex).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 Ruby, if nil 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=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)

top log the error to MkLogFileC (default: stderr) … → API: rbmkkernel_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=nil → 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=nil?, ?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: rbmkkernel_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: rbmkkernel_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: rbmkkernel_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) → nil 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: rbmkkernel_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: rbmkkernel_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 rbmkkernel function and therefore never becomes nil 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 nil 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 nil if invalid… → API: rbmkkernel_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 nil if netHdl is invalid

MK_HDL lfl.HandleGet()

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

The head-instance is the last instance created.

MkLogFileC lfl.Next()

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

MkLogFileC lfl.Prev()

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

MkLogFileC CLASS MISC

MkLogFileC - Misc class functions …

(static) MkLogFileC MkLogFileC.GetNull()

top Null-Slot - return a MkLogFileC typed NULL instance … → API: rbmkkernel_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: rbmkkernel_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 nil

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

top open the log-file in append mode … → API: rbmkkernel_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 nil

(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: rbmkkernel_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: rbmkkernel_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 rbmkkernel 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 rbmkkernel 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_rb_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: rbmkkernel_MkRuntimeC_GetDebug

(static) MkErrorE MkRuntimeC.GetErrorCode()

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

(static) bool MkRuntimeC.GetIsSilent()

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

(static) string MkRuntimeC.GetLogfile()

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

Attention

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

(static) MkRuntimeC.SetDebug(dbg:int32)

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

(static) MkRuntimeC.SetIsSilent(silent:bool)

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

(static) MkRuntimeC.SetLogfile(logfile:string)

top set the MkRuntimeS::logfile value and cleanup old value … → API: rbmkkernel_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 nil or ""

MkRuntimeC INFO

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

rt.Log(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)

top log the MkRuntimeC … → API: rbmkkernel_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=nil → use the doc_mk_rb_runtime-default)
[in]	fmtobj	managed object used to format the log-message (default=nil → 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 Ruby binary.

---

EXAMPLES

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

  def BUF2
    SendSTART()
    for i in 1..3 do
      buf = ReadBUF()
      SendSTR(buf.GetType1())
      SendBUF(buf)
    end
    SendRETURN()
  end

---

SEE ALSO

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

KEYWORDS

Ruby, unix, socket, message, msgque