theKernel 10.0 NHI1 - theKernel - theLink - theConfig - theSq3Lite - theCompiler - theBrain - theGuard
c - tcl - cs - py - rb - jv - cc
Loading...
Searching...
No Matches
jvmkkernel

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

SYNOPSIS

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

  • import jvmkkernel.*; 

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

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

To access all features without jvmkkernel prefix use:

  • import jvmkkernel.*; 

Using the jvmkkernel package ...

JAVA package libraries
jvmkkernel.jar
A JAR ("Java archive") file is a package file format typically used to aggregate many Java class files and associated metadata and resources (text, images, etc.) into one file for distribution.
libjvmkkernel.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.
libjvmkkernel.la
A .la file is a text file used by the GNU libtools package to describe the files that make up the corresponding library.
> man java

To access the jvmkkernel package the commandline-option --class-path or the environment variable CLASSPATH have to include the directory.

--class-path classpath, -classpath classpath, or -cp classpath

    A semicolon (;) separated list of directories, JAR archives, and ZIP archives to search for class files.

    Specifying classpath overrides any setting of the CLASSPATH environment variable. If the class path option 
    isn't used and classpath isn't set, then the user class path consists of the current directory (.).

    As a special convenience, a class path element that contains a base name of an asterisk (*) is considered 
    equivalent to specifying a list of all the files in the directory with the extension .jar or .JAR . 
    A Java program can't tell the difference between the two invocations. For example, if the directory mydir contains 
    a.jar and b.JAR, then the class path element mydir/* is expanded to A.jar:b.JAR, except that the order of JAR files 
    is unspecified. All .jar files in the specified directory, even hidden ones, are included in the list. A class 
    path entry consisting of an asterisk (*) expands to a list of all the jar files in the current directory. The 
    CLASSPATH environment variable, where defined, is similarly expanded. Any class path wildcard expansion that 
    occurs before the Java VM is started. Java programs never see wildcards that aren't expanded except by querying the 
    environment, such as by calling System.getenv("CLASSPATH").
JAVA initialization hint
JAVA error: java.lang.UnsatisfiedLinkError

If everything compiles fine but the start of the final application failes with: (example)

> Nhi1Exec MyTest.java
exec[#2] -> '/usr/bin/java' 'example.MyTest'
Exception in thread "main" java.lang.UnsatisfiedLinkError: 'jvmkkernel.MkErrorE jvmkkernel.MkKernel.ErrorE_FromInt(int)'
        at jvmkkernel.MkKernel.ErrorE_FromInt(Native Method)
        at example.MyTest.main(MyTest.java:16)

than the initinal MkKernel.Setup(); is missing and the jni library was not loaded.


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 jvmkkernel library and is responsible for the quality-target of the entire project.
  • implementation of the managed-object technology
  • 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.
Target
!! This documentation describe the implementation-layer and target the Java programmer. !!

PACKAGE

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

The jvmkkernel package is loaded with:

import jvmkkernel.*; 

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

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

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

jvmkkernel is also called as Programming-Language-Micro-Kernel (PLMK). jvmkkernel is like a programming-language without syntax but using the Target-Programming-Language (in our case Java) 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 jvmkkernel 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 jvmkkernel-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 boolean 1 byte boolean value using true or false
I8 Y byte 1 byte signed character
I16 S short 2 byte signed short
I32 I int 4 byte signed integer
I64 W long 8 byte signed long long integer
FLT F float 4 byte float
DBL D double 8 byte double
BIN B byte[] 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 (byte[])
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 jvmkkernel to provide temporary storage. It is a common design pattern that jvmkkernel 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 jvmkkernel 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 Java 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 jvmkkernel 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.java ReadBFL overwrite previous ReadBFL

  class BFL2 implements MqServiceIF {
    public void Callback(MqContextC ctx) {
      var tmp1 = ctx.ReadBFL()                    ; // "tmp1" is now a reference to the FLS storage of "ReadBFL"
      var tmp2 = ctx.ReadBFL()                    ; // ERROR: the "tmp2" is using a SHARED reference with "tmp1"
      ctx.Send("R","LL",tmp1,tmp2)                ; // ERROR: "tmp1" and "tmp2" are the SAME values
    }
  }

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

  class pBFL3 implements MqServiceIF {
    private MkBufferListC  tmp2;
    public void Callback(MqContextC ctx) {
      tmp2 = ctx.ReadBFL()                        ; // ERROR: the "tmp2" is using a SHARED reference with "tmp1"
    }
  }
  class BFL3 implements MqServiceIF {
    public void Callback(MqContextC ctx) {
      var tmp1 = ctx.ReadBFL()                    ; // "tmp1" is now a reference to the FLS storage of "ReadBFL"
      Send("C",new pBFL3(),"ECOL:[III]",4,5,6)    ; // ATTENTION: callback "pBFL3" using "ReadBFL"
      ctx.ProcessEvent(MqWaitOnEventE.OWN)        ; // ERROR: enter event-loop, callback "pBFL3" is called
      ctx.Send("R","L",tmp1)                      ; // ERROR: "tmp1" has now the value from "tmp2"
    }
  }

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

  class BFL4 implements MqServiceIF {
    public void Callback(MqContextC ctx) {
      var tmp1 = ctx.ReadBFL()                    ; // "tmp1" is now a reference to the FLS storage of "ReadBFL"
      var glb1 = tmp1.Dup()                       ; // OK: "glb1" is now a UNSHARED reference to the global memory
      var tmp2 = ctx.ReadBFL()                    ; // "tmp2" is now a reference to the FLS storage of "ReadBFL"
      ctx.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
    }
  }

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

  class BUST implements MqServiceIF {
    public void Callback(MqContextC ctx) {
      MkBufferStreamC bus = MkBufferStreamC.CreateTLS("perfserver-BUST" );
      while (ReadItemExists()) {
        bus.WriteBUF(ReadBUF());
      }
      bus.PosToStart();
      SendSTART();
      while (bus.ReadItemExists()) {
        SendBUF(bus.ReadBUF());
      }
      SendRETURN();
    }
  }

Example from LibSq3LiteRpcClient.tcl callback dealing the temporary TLS data

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

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

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

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

MkKernel PACKAGE

MkKernel SETUP

MkKernel PACKAGE - Setup und Cleanup the jvmkkernel

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

import jvmkkernel.*; 

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

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

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

setup jvmkkernel internal memory …

MkKernel SETUP DETAILS

C-API: MkKernel_Setup_libmkkernel_C_API - MkKernel PACKAGE - Setup und Cleanup the jvmkkernel

Initializing a jvmkkernel 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 jvmkkernel 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 jvmkkernel library startup functions

MK_EXTERN void MK_DECL MkSetup (void) __attribute__ ((constructor(200)));
MK_EXTERN void MK_DECL MkCleanup (void) __attribute__ ((destructor(200)));
#define MK_DECL
#define MK_EXTERN
static library
void MkSetup(void)
setup jvmkkernel internal memory …
void MkCleanup(void)
cleanup jvmkkernel internal memory …

In the Programming-Language-Micro-Kernel (PLMK), a type is defined for each thread, which means that the new jvmkkernel library must be known when the thread starts. This is not a problem as long as the external jvmkkernel library is linked to the application. However, if dlopen is used to load the jvmkkernel library, the current restriction is that the new data type from the jvmkkernel 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] Cleanup()

top cleanup jvmkkernel internal memory … → API: jvmkkernel::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] Setup()

top setup jvmkkernel internal memory … → API: jvmkkernel::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: jvmkkernel::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_ERROR = 2,
};

[static] MkErrorE ErrorE_FromInt(int value)

top return the MkErrorE from integer … → API: jvmkkernel::MkKernel::ErrorE_FromInt

[static] int ErrorE_ToInt(MkErrorE value)

top return the MkErrorE as integer … → API: jvmkkernel::MkKernel::ErrorE_ToInt

[static] String ErrorE_ToString(MkErrorE value)

top return the MkErrorE as string … → API: jvmkkernel::MkKernel::ErrorE_ToString


enum MkIdSE

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

[static] MkIdSE IdSE_FromInt(int value)

top return the MkIdSE from integer … → API: jvmkkernel::MkKernel::IdSE_FromInt

[static] int IdSE_ToInt(MkIdSE value)

top return the MkIdSE as integer … → API: jvmkkernel::MkKernel::IdSE_ToInt

[static] String IdSE_ToString(MkIdSE value)

top return the MkIdSE as string … → API: jvmkkernel::MkKernel::IdSE_ToString


enum MkTimeoutE

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

[static] MkTimeoutE TimeoutE_FromInt(int value)

top return the MkTimeoutE from integer … → API: jvmkkernel::MkKernel::TimeoutE_FromInt

[static] int TimeoutE_ToInt(MkTimeoutE value)

top return the MkTimeoutE as integer … → API: jvmkkernel::MkKernel::TimeoutE_ToInt

[static] String TimeoutE_ToString(MkTimeoutE value)

top return the MkTimeoutE as string … → API: jvmkkernel::MkKernel::TimeoutE_ToString


enum MkTypeE

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

See also
MkTypeE_ToString, MkTypeE_ToInt, MkTypeE_FromInt, BufferGetType2, BufferCastTo, BufferStreamReadGetNextType

[static] MkTypeE TypeE_FromInt(int value)

top return the MkTypeE from integer … → API: jvmkkernel::MkKernel::TypeE_FromInt

[static] int TypeE_ToInt(MkTypeE value)

top return the MkTypeE as integer … → API: jvmkkernel::MkKernel::TypeE_ToInt

[static] String TypeE_ToString(MkTypeE value)

top return the MkTypeE as string … → API: jvmkkernel::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-Java-Instance and the jvmkkernel-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 jvmkkernel error …
IsNull ckeck if the object is null
ToError Error-Slot - return an error-object pre initialized with obj data.
ToName Info-Slot - returns brief information about the obj as a string
ToNameOfClass Class-Slot - returns the Java-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 …

jvmkkernel is also called as Programming-Language-Micro-Kernel (PLMK). jvmkkernel is like a programming-language without syntax but using the Target-Programming-Language (in our case Java) 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 jvmkkernel 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 null if invalid…
HandleDelete Handle-Delete-Slot - delete a netObj from handle-storage …
HandleExists check if obj has already a handle defined…
HandleGet Handle-Get-Slot - returns a export-hdl to the MkObjectC useable for external storage
HandleGetOfType Export-Slot - returns typeHdl of the obj .
HandleGetOr0

return export-hdl or 0 in not created…

MkObjectC CLASS INTROSPECTION

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

get previous instance from linked-list of MkObjectS type

MkObjectC CLASS MISC

GetNull

Null-Slot - return a MkObjectC typed NULL instance …

MkObjectC CLASS DETAILS

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

MkObjectC CLASS EXPORT

MkObjectC - Export class functions …

[static] MkObjectC.HandleDeleteByNetHdl(int netHdl)

top Handle-Delete-Slot - delete a netHdl from handle-storage … → API: jvmkkernel::MkObjectC::HandleDeleteByNetHdl

[static] MkObjectC MkObjectC.HandleResolve(int netHdl)

top Handle-Resolve-Slot - return a MkObjectC from netHdl or null if invalid… → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]netHdlhandle former exported with MkObjectHandleGet
Returns
the required handle or null if netHdl is invalid

netObj.HandleDelete()

top Handle-Delete-Slot - delete a netObj from handle-storage … → API: jvmkkernel::MkObjectC::HandleDelete

boolean obj.HandleExists()

top check if obj has already a handle defined… → API: jvmkkernel::MkObjectC::HandleExists

Parameters
[in]objthe MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
Returns
true or false

int obj.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkObjectC useable for external storage → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe 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

int obj.HandleGetOfType()

top Export-Slot - returns typeHdl of the obj . → API: jvmkkernel::MkObjectC::HandleGetOfType

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

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

int obj.HandleGetOr0()

top return export-hdl or 0 in not created… → API: jvmkkernel::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]objthe 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: jvmkkernel::MkObjectC::Instances

The head-instance is the last instance created.

MkObjectC obj.Next()

top get next instance from linked-list of MkObjectS type → API: jvmkkernel::MkObjectC::Next

MkObjectC obj.Prev()

top get previous instance from linked-list of MkObjectS type → API: jvmkkernel::MkObjectC::Prev

MkObjectC CLASS MISC

MkObjectC - Misc class functions …

[static] MkObjectC MkObjectC.GetNull()

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

MkObjectC TOR

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

[static] MkObjectC.DeleteCallbackCleanup(String ident)

top cleanup the DeleteCallback installed with MkObjectDeleteCallbackSetup … → API: jvmkkernel::MkObjectC::DeleteCallbackCleanup

See also
MkObjectDeleteCallbackSetup

[static] MkObjectC.DeleteCallbackSetup(String ident, ?MkObjectDeleteIF callback = null?, ?String filter = null?)

top Create/Delete the instance-delete-callback … → API: jvmkkernel::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 null than the callback with name ident is deleted if exists and no new callback is created.
  • If null then it is identical to MkObjectDeleteCallbackCleanup(ident).

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

  • The filter is optional and is only used if not null and not "":
  • The filter is applied to MkTypeS::type_name like MkBufferC.
  • The POSIX Extended Regular Expression syntax is defined in man 7 regex.
  • If the filter is not used, the fCall is called on every instance deletion !
C-callback definition details:
Read more at MkObjectDeleteCallF
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]identIdentify the callback, have to ne non null and not "".
[in]fCall(C-Only) Internal required: the callback, if null than the callback is deleted.
[in]callbackOptional: the parameter for fcall, for cleanup use fFree.
[in]fFree(C-Only) Internal optional: cleanup callback data
[in]filterOptional: is an regular expression to filter for MkTypeS::type_name.
See also
MkObjectDeleteCallbackCleanup
MkObjectDeleteCallbackSetup : overload
public native static void DeleteCallbackSetup (String ident, MkObjectDeleteIF callback, String filter);
public static void DeleteCallbackSetup (String ident) {
DeleteCallbackSetup (ident, null, null);
}
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: jvmkkernel::MkObjectC::Delete

There are two different ways to delete an instance:

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

[destructor] obj.Dispose()

top Dispose-Slot - untie the connection between the Native-Java-Instance and the jvmkkernel-Instance. → API: jvmkkernel::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(String message, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

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

obj.DbgDump(?String message = "var"?, ?String callfunc = null?)

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

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

fmtobj.DbgL(String message, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

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

The marker is prefixed with object data from th fmtobj.

obj.DbgLogC(?String callfunc = null?)

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

obj.DbgO(?String callfunc = null?)

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

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

This function can be overwritten in the target programming language.

fmtobj.DbgSTACK(?int skip = 0?, ?int num = -1?, ?String callfunc = null?)

top debug: write the stack-trace to MkLogFileC (default: stderr) … → API: jvmkkernel::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.

possible values are:

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

Many logging functions have common parameters:

Parameters
[in]fmtobjmanaged object used to format the log-message (default=null → use default-format)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]debugthe debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)

fmtobj.LogC(String message, ?int debug = 0?, ?String callfunc = null?)

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

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

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

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

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

fmtobj.LogHEX(?String callfunc = null?, byte[] data)

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

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

obj.Log(?MkObjectC fmtobj = null?, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

top Log-Slot - log a summary of an object to the MkLogFileC (default: stderr) target … → API: jvmkkernel::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)

#define MkBufferST
instance-type as MkSuperTypeS-class-type …
void MkBufferLog_RT(MK_RT mkrt, MK_BUFN const buf, MK_OBJN fmtobj, MK_DBG const debug, MK_STRN const callfunc, MK_I32 const lvl)
log the MkBufferC …
void(* MkLogF)(MK_RT mkrt, MK_OBJN const obj, MK_OBJN fmt, MK_I32 const debug, MK_STRN const prefix, MK_I32 const lvl)
#define MkTYP_R(x)
cast a known-managed-object into an MkTypeS reference

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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
[in]fmtobjmanaged object used to format the log-message (default=null → use default-format)
[in]debugthe debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0)
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
[in]lvla user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0)
See also
MkBufferLog, MkBufferListLog, MkBufferStreamLog, ?MkLogFileLog, MkErrorLog, MkRuntimeLog, MkObjectLog

obj.LogDetail(?MkObjectC fmtobj = null?, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

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

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

obj.LogSimple(?MkObjectC fmtobj = null?, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

top log the MkObjectS into the MkLogFileC (default: stderr) … → API: jvmkkernel::MkObjectC::LogSimple

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

MkObjectC MISC

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

MkErrorC obj.ErrorCatch(?Throwable exception = null?, ?String callfunc = null?)

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

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

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

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

	  cl[id].SendSTART();
	  try {
	    ProxyItem(cl[id]);
	    cl[id].SendEND_AND_WAIT("ECOI", 5);
	  } catch (Throwable ex) {
	    MkErrorC err = ErrorCatch(ex);
	    SendI32(err.GetNum());
	    SendSTR(err.GetText());
	    err.Reset();
	  }
Note
The C language does not support the MkErrorCatch because there is no native error object.
If there is no error at all the MkErrorCatch does nothing and just return the MkErrorDEFAULT.
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe MkObjectS instance to work on - a MANAGED OBJECT after type-check and able to be supported by the MkObjectS API
[in]exceptionthe exception object from Java, if null the global exception object is used
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
Returns
the ErrorDEFAULT initialized with exception value
See also
err.Raise() err.Reset(?String callfunc = null?, ?int callline = -1?, ?boolean force = false?)

boolean obj.IsNull()

top ckeck if the object is null → API: jvmkkernel::MkObjectC::IsNull

MkErrorC obj.ToError()

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

String obj.ToName()

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

String obj.ToNameOfClass()

top Class-Slot - returns the Java-Class-Name of the obj as string → API: jvmkkernel::MkObjectC::ToNameOfClass

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

ObjectToNameOfType returns the name of the jvmkkernel type
ObjectToNameOfClass returns the name of the Java class

String obj.ToNameOfType()

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

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

ObjectToNameOfType returns the name of the libmsgque type
ObjectToNameOfClass returns the name of the Java class
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]objthe 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: jvmkkernel::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]mkrtthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MkBufferC

MkBufferC CLASS

Export MkBufferC - Export class functions …
Introspection MkBufferC - Introspection class functions …
Misc

MkBufferC - Misc class functions …

MkBufferC TOR

Create Constructor - create a new MkBufferC with minimum size of internal storage …
CreateTT Constructor - create a new MkBufferC with an PRIMITIVE TYPE
CreateTLS same as BufferCreate but require no cleanup
CreateBUF Constructor - create a new MkBufferC with an PRIMITIVE TYPE
Create64 call the BufferCreate with default type MkBuffer64S (64 byte) …
Create256 call the BufferCreate with default type MkBuffer256S (256 byte) …
Create1024 call the BufferCreate with default type MkBuffer1024S (1024 byte) …
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 jvmkkernel is working on data… jvmkkernel 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 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(?int size = 0?) jvmkkernel.MkBufferC(wide size = 0)
[destructor] buf.Delete() buf.Dispose()

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

class BUF2 implements MqServiceIF {
  public void Callback(MqContextC ctx) {
    ctx.SendSTART();

    for (int i=0; i<3; i++) {
      MkBufferC buf = ctx.ReadBUF();
      ctx.SendSTR(Character.toString(buf.GetType1()));
      ctx.SendBUF(buf);
    }

    ctx.SendRETURN();
  }
}
See also
BufferGetType1 BufferGetType2 BufferGetType3

MkBufferC CLASS

NAVI: top, up

MkBufferC CLASS EXPORT

HandleResolve Handle-Resolve-Slot - return a MkBufferC from netHdl or null if invalid…
HandleGet

Handle-Get-Slot - returns a export-hdl to the MkBufferC useable for external storage

MkBufferC CLASS INTROSPECTION

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

get previous instance from linked-list of MkBufferS type

MkBufferC CLASS MISC

GetNull

Null-Slot - return a MkBufferC typed NULL instance …

MkBufferC CLASS DETAILS

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

MkBufferC CLASS EXPORT

MkBufferC - Export class functions …

[static] MkBufferC MkBufferC.HandleResolve(int netHdl)

top Handle-Resolve-Slot - return a MkBufferC from netHdl or null if invalid… → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]netHdlhandle former exported with MkBufferHandleGet
Returns
the required handle or null if netHdl is invalid

int buf.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkBufferC useable for external storage → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe 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: jvmkkernel::MkBufferC::Instances

The head-instance is the last instance created.

MkBufferC buf.Next()

top get next instance from linked-list of MkBufferS type → API: jvmkkernel::MkBufferC::Next

MkBufferC buf.Prev()

top get previous instance from linked-list of MkBufferS type → API: jvmkkernel::MkBufferC::Prev

MkBufferC CLASS MISC

MkBufferC - Misc class functions …

[static] MkBufferC MkBufferC.GetNull()

top Null-Slot - return a MkBufferC typed NULL instance … → API: jvmkkernel::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(?int size = 0?)

top Constructor - create a new MkBufferC with minimum size of internal storage … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]typeA type defined as MkTypeS with a TT postfix (default: MkBuffer64S, possible: MkBuffer64S, MkBuffer256S and MkBuffer1024S)
[in]sizeThe initial size of the instance-local-storage. The MkBufferC has dynamic-memory-management, the size value is just a hint to provide enought memory for future tasks. The real size created is the maximum of type-ILS-size and size . (default: 0 = use the type-ILS-size)
Returns
The newly created MkBufferC instance, the instance is owned by the caller
See also
BufferDelete BufferDup MqReadBUF

[static] MkBufferC MkBufferC.CreateTLS(String tlsName, ?boolean resetB = true?)

top same as BufferCreate but require no cleanup → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]tlsNameAn per-thread unique name (string) to identify the reuse-able instance-storage. if tlsName is null or "" than a null is returned
[in]resetBshould 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(MkBufferC val)

top Constructor - create a new MkBufferC with an PRIMITIVE TYPE … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]valthe PRIMITIVE TYPE object as data-source

[constructor,static] MkBufferC MkBufferC.Create64(?int size = 0?)

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

[constructor,static] MkBufferC MkBufferC.Create256(?int size = 0?)

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

[constructor,static] MkBufferC MkBufferC.Create1024(?int size = 0?)

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

[destructor] buf.Delete()

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

There are two different ways to delete an instance:

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe 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: jvmkkernel::MkBufferC::Merge

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe MkBufferS instance to work on
Returns
The new instance or null on error or if no Merge-Constructor is available
Attention
The new instance have to be deleted with BufferDelete
See also
BufferDup BufferResetFull BufferDelete

[constructor,static] MkBufferC.CreateTT(byte val)

top

The BufferCreateTT provide a single function for every PRIMITIVE TYPE

attributereturncommand

C-API :

[constructor,static] MkBufferCMkBufferC.CreateI8(byte val)MkBufferCreateI8_RT
[constructor,static] MkBufferCMkBufferC.CreateI16(short val)MkBufferCreateI16_RT
[constructor,static] MkBufferCMkBufferC.CreateI32(int val)MkBufferCreateI32_RT
[constructor,static] MkBufferCMkBufferC.CreateI64(long val)MkBufferCreateI64_RT
[constructor,static] MkBufferCMkBufferC.CreateSTR(String val)MkBufferCreateSTR_RT
[constructor,static] MkBufferCMkBufferC.CreateBIN(byte[] val)MkBufferCreateBIN_RT
[constructor,static] MkBufferCMkBufferC.CreateBOL(boolean val)MkBufferCreateBOL_RT
[constructor,static] MkBufferCMkBufferC.CreateFLT(float val)MkBufferCreateFLT_RT
[constructor,static] MkBufferCMkBufferC.CreateDBL(double val)

MkBufferCreateDBL_RT

Constructor - create a new MkBufferC with an PRIMITIVE TYPE

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

Returns
The newly created MkBufferC instance, the instance is owned by the caller
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]valthe PRIMITIVE TYPE object as data-source

MkBufferC SET

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

MkBufferC buf.SetBinaryR(byte[] val)

top Set the MkBufferC to the val … → API: jvmkkernel::MkBufferC::SetBinaryR

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

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

MkBufferC buf.SetBUF(MkBufferC val)

top Set the MkBufferC to the val … → API: jvmkkernel::MkBufferC::SetBUF

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

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

MkBufferC buf.SetStringR(String val)

top Set the MkBufferC to the val … → API: jvmkkernel::MkBufferC::SetStringR

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

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

buf.SetTT(byte val)

top

The BufferSetTT provide a single function for every PRIMITIVE TYPE

attributereturncommand

C-API :

MkBufferCbuf.SetI8(byte val)MkBufferSetI8_RT
MkBufferCbuf.SetI16(short val)MkBufferSetI16_RT
MkBufferCbuf.SetI32(int val)MkBufferSetI32_RT
MkBufferCbuf.SetI64(long val)MkBufferSetI64_RT
MkBufferCbuf.SetSTR(String val)MkBufferSetSTR_RT
MkBufferCbuf.SetBIN(byte[] val)MkBufferSetBIN_RT
MkBufferCbuf.SetBOL(boolean val)MkBufferSetBOL_RT
MkBufferCbuf.SetFLT(float val)MkBufferSetFLT_RT
MkBufferCbuf.SetDBL(double val)

MkBufferSetDBL_RT

Set the MkBufferC to the val

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

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

MkBufferC GET

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

MkBufferListC buf.GetBFL(?MkBufferListC val_inout = null?)

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe MkBufferS instance to work on
[in,out]val_inoutthe reference object or null at error
  • The reference object have to be non null.
  • If reference object is a refrence to a non null object than the reference object is populated with the result.
  • If reference object is a refrence to a null object than :
    • The reference object is set to the TLS alocated object owned by the Programming-Language-Micro-Kernel (PLMK).
    • (do not free) The memory of the reference object value belongs to the called jvmkkernel function and therefore never becomes null for a non-error result.
      For details on the reference object value, see: MkKernel_Storage_C_API.
  • The newly created reference-object is owned by the caller.
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

MkBufferC buf.GetBUF()

top get a val_out from a MkBufferC … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) - (nonnull)
[in]bufthe MkBufferS instance to work on - (nonnull)
[out]val_outthe 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: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) - (nonnull)
[in]bufthe MkBufferS instance to work on - (nonnull)
[out]val_outthe 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

attributereturncommand

C-API :

bytebuf.GetI8()MkBufferGetI8_RT
shortbuf.GetI16()MkBufferGetI16_RT
intbuf.GetI32()MkBufferGetI32_RT
longbuf.GetI64()MkBufferGetI64_RT
Stringbuf.GetSTR()MkBufferGetSTR_RT
byte[]buf.GetBIN()MkBufferGetBIN_RT
booleanbuf.GetBOL()MkBufferGetBOL_RT
floatbuf.GetFLT()MkBufferGetFLT_RT
doublebuf.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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) - (nonnull)
[in]bufthe MkBufferS instance to work on - (nonnull)
[out]val_outthe value to return - (nonnull)

MkBufferC ACCESS

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

MkBufferC buf.AppendSTR(String val)

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

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

Example from server.java 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(String val)

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

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

Example from server.java 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);

int buf.Pop(String val)

top delete str from the MkBufferC … → API: jvmkkernel::MkBufferC::Pop

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

int buf.Push(String val)

top add str to the MkBufferC … → API: jvmkkernel::MkBufferC::Push

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

Object 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

char buf.GetType1()

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

MK_BUFN const 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: jvmkkernel::MkBufferC::GetType2

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

String buf.GetType3()

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

MK_BUFN const 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 "*";
}

boolean buf.IsLocal()

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

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

buf.Log(?MkObjectC fmtobj = null?, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

top log the MkBufferC … → API: jvmkkernel::MkObjectC::Log

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

buf.LogS(?String varname = "buf"?, ?MkObjectC fmtobj = null?, ?String callfunc = null?)

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

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

MkBufferC MISC

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

buf.CastTo(MkTypeE typ)

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bufthe MkBufferS instance to work on
[in]typcast buf to typ
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

int buf1.Cmp(MkBufferC buf2)

top compare TWO MkBufferC objects like strcmp do it for strings … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]buf1the FIRST MkBufferC object to compare
[in]buf2the SECOND MkBufferC object to compare
Returns
Returns < 0 if buf1 is less than buf2; > 0 if buf1 is greater than buf2, and 0 if they are equal.

MkBufferC buf.Copy(MkBufferC srce)

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

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

MkBufferC buf.Reset()

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

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

buf.ResetFull()

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

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

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

MkBufferC buf.SizeAdd(int size)

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

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

MkBufferC buf.SizeNew(int size)

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

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

MkBufferC buf.Temp()

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

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

Parameters
[in]mkrtthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

String inst.ToString()

top String-Slot - returns the string representation of the inst … → API: jvmkkernel::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]mkrtthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MkBufferStreamC

MkBufferStreamC CLASS

Export MkBufferStreamC - Export class functions …
Introspection MkBufferStreamC - Introspection class functions …
Misc

MkBufferStreamC - Misc class functions …

MkBufferStreamC TOR

Create create and initialize an MkBufferStreamC instance …
Create64 call the BufferStreamCreate with default type MkBufferStream64S (64 byte) …
Create256 call the BufferStreamCreate with default type MkBufferStream256S (256 byte) …
Create1024 call the BufferStreamCreate with default type MkBufferStream1024S (1024 byte) …
Create16384 call the BufferStreamCreate with default type MkBufferStream16384S (16384 byte) …
CreateTLS same as BufferStreamCreate but require no cleanup …
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 null if invalid…
HandleGet

Handle-Get-Slot - returns a export-hdl to the MkBufferStreamC useable for external storage

MkBufferStreamC CLASS INTROSPECTION

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

get previous instance from linked-list of MkBufferStreamS type

MkBufferStreamC CLASS MISC

GetNull

Null-Slot - return a MkBufferStreamC typed NULL instance …

MkBufferStreamC CLASS DETAILS

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

MkBufferStreamC CLASS EXPORT

MkBufferStreamC - Export class functions …

[static] MkBufferStreamC MkBufferStreamC.HandleResolve(int netHdl)

top Handle-Resolve-Slot - return a MkBufferStreamC from netHdl or null if invalid… → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]netHdlhandle former exported with MkBufferStreamHandleGet
Returns
the required handle or null if netHdl is invalid

int bus.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkBufferStreamC useable for external storage → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe 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: jvmkkernel::MkBufferStreamC::Instances

The head-instance is the last instance created.

MkBufferStreamC bus.Next()

top get next instance from linked-list of MkBufferStreamS type → API: jvmkkernel::MkBufferStreamC::Next

MkBufferStreamC bus.Prev()

top get previous instance from linked-list of MkBufferStreamS type → API: jvmkkernel::MkBufferStreamC::Prev

MkBufferStreamC CLASS MISC

MkBufferStreamC - Misc class functions …

[static] MkBufferStreamC MkBufferStreamC.GetNull()

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

MkBufferStreamC TOR

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

[constructor,static] MkBufferStreamC MkBufferStreamC.Create(?int size = 0?)

top create and initialize an MkBufferStreamC instance … → API: jvmkkernel::MkBufferStreamC::Create

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

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

[constructor,static] MkBufferStreamC MkBufferStreamC.Create64(?int size = 0?)

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

[constructor,static] MkBufferStreamC MkBufferStreamC.Create256(?int size = 0?)

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

[constructor,static] MkBufferStreamC MkBufferStreamC.Create1024(?int size = 0?)

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

[constructor,static] MkBufferStreamC MkBufferStreamC.Create16384(?int size = 0?)

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

[static] MkBufferStreamC MkBufferStreamC.CreateTLS(String tlsName, ?boolean resetB = true?)

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

  class BUST implements MqServiceIF {
    public void Callback(MqContextC ctx) {
      MkBufferStreamC bus = MkBufferStreamC.CreateTLS("perfserver-BUST" );
      while (ReadItemExists()) {
        bus.WriteBUF(ReadBUF());
      }
      bus.PosToStart();
      SendSTART();
      while (bus.ReadItemExists()) {
        SendBUF(bus.ReadBUF());
      }
      SendRETURN();
    }
  }
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]tlsNameAn per-thread unique name (string) to identify the reuse-able instance-storage. if tlsName is null or "" than a null is returned
[in]resetBshould 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

[destructor] bus.Delete()

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

There are two different ways to delete an instance:

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

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on - (nonnull)
Returns
The new instance or null on error or if no Merge-Constructor is available
Attention
The new instance have to be deleted with BufferStreamDelete
See also
BufferStreamDup BufferStreamResetFull BufferStreamDelete

MkBufferStreamC 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(?MkBufferListC val_inout = null?)

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[in,out]val_inoutthe reference object or null at error
  • The reference object have to be non null.
  • If reference object is a refrence to a non null object than the reference object is populated with the result.
  • If reference object is a refrence to a null object than :
    • The reference object is set to the TLS alocated object owned by the Programming-Language-Micro-Kernel (PLMK).
    • (do not free) The memory of the reference object value belongs to the called jvmkkernel function and therefore never becomes null for a non-error result.
      For details on the reference object value, see: MkKernel_Storage_C_API.
  • The newly created reference-object is owned by the caller.
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
See also
BufferStreamReadBFL

MkBufferListC bus.ReadBFL()

top read a MkBufferListC from the MkBufferStreamC … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[out]val_outthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MkBufferC bus.ReadBUF()

top read a val_out from the MkBufferStreamC … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[out]val_outthe new value

MkTypeE bus.ReadGetNextType()

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

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

int bus.ReadGetNumItems()

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

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

boolean bus.ReadItemExists()

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

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

bus.ReadL_END()

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

bus.ReadL_START(?MkBufferC buf = null?)

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[in]bufnull 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: jvmkkernel::MkBufferStreamC::ReadLONG

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[out]val_outthe 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(long val)

bus.ReadUndo()

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

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

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

attributereturncommand

C-API :

bytebus.ReadI8()MkBufferStreamReadI8_RT
intbus.ReadI32()MkBufferStreamReadI32_RT
longbus.ReadI64()MkBufferStreamReadI64_RT
Stringbus.ReadSTR()MkBufferStreamReadSTR_RT
byte[]bus.ReadBIN()MkBufferStreamReadBIN_RT
booleanbus.ReadBOL()MkBufferStreamReadBOL_RT
floatbus.ReadFLT()MkBufferStreamReadFLT_RT
doublebus.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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[out]val_outthe 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(MkBufferListC bfl)

top write a MkBufferListC into the MkBufferStreamC … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[in]bflthe MkBufferListC to insert
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
See also
BufferStreamWriteL_FLAT BufferStreamReadBFL

bus.WriteBUF(MkBufferC val)

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[in]valthe new PRIMITIVE TYPE
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

bus.WriteBUS_FLAT(MkBufferStreamC add)

top write a MkBufferStreamC into the MkBufferStreamC … → API: jvmkkernel::MkBufferStreamC::WriteBUS_FLAT

The add is appended to bus

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[in]addthe MkBufferStreamC to append
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

bus.WriteHDL(int val)

top write the handle into the MkBufferStreamC … → API: jvmkkernel::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:

bus.WriteL_END()

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

bus.WriteL_FLAT(MkBufferListC bfl)

top write a MkBufferListC FLAT into the MkBufferStreamC … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[in]bflthe 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: jvmkkernel::MkBufferStreamC::WriteL_START

bus.WriteLONG(long val)

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[in]valthe 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(byte val)

top

The BufferStreamWriteTT provide a single function for every PRIMITIVE TYPE

attributereturncommand

C-API :

bus.WriteI8(byte val)MkBufferStreamWriteI8_RT
bus.WriteI32(int val)MkBufferStreamWriteI32_RT
bus.WriteI64(long val)MkBufferStreamWriteI64_RT
bus.WriteSTR(String val, ?int len = -1?)MkBufferStreamWriteSTR_RT
bus.WriteBIN(byte[] val)MkBufferStreamWriteBIN_RT
bus.WriteBOL(boolean val)MkBufferStreamWriteBOL_RT
bus.WriteFLT(float val)MkBufferStreamWriteFLT_RT
bus.WriteDBL(double val)

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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
[in]valthe 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(MkBufferStreamC src)

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

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

bus.Log(?MkObjectC fmtobj = null?, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

top log the MkBufferStreamC … → API: jvmkkernel::MkObjectC::Log

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

bus.PosToStart()

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

MkBufferStreamC bus.Reset()

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

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

bus.ResetFull()

top reset a MkBufferStreamC to the length zero and free allocated storage… → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe MkBufferStreamS instance to work on
See also
MkBufferStreamC bus.Reset()

MkBufferListC bus.ToBFL()

top convert the bus into a MkBufferListC … → API: jvmkkernel::MkBufferStreamC::ToBFL

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]busthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

String inst.ToString()

top String-Slot - returns the string representation of the inst … → API: jvmkkernel::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]mkrtthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MkBufferListC

MkBufferListC CLASS

Export MkBufferListC - Export class functions …
Introspection MkBufferListC - Introspection class functions …
Misc

MkBufferListC - Misc class functions …

MkBufferListC TOR

Create Constructs a MkBufferC instance with size storage…
CreateLA Constructs a MkBufferListC instance with an other MkBufferListC OR a list of arguments (only in NON C)
CreateTLS same as BufferListCreate but require no cleanup …
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(?int size = 0?) jvmkkernel.MkBufferListC(int num = 0)
[destructor] bfl.Delete() bfl.Dispose()

MkBufferListC CLASS

NAVI: top, up

MkBufferListC CLASS EXPORT

HandleResolve Handle-Resolve-Slot - return a MkBufferListC from netHdl or null if invalid…
HandleGet

Handle-Get-Slot - returns a export-hdl to the MkBufferListC useable for external storage

MkBufferListC CLASS INTROSPECTION

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

get previous instance from linked-list of MkBufferListS type

MkBufferListC CLASS MISC

GetNull

Null-Slot - return a MkBufferListC typed NULL instance …

MkBufferListC CLASS DETAILS

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

MkBufferListC CLASS EXPORT

MkBufferListC - Export class functions …

[static] MkBufferListC MkBufferListC.HandleResolve(int netHdl)

top Handle-Resolve-Slot - return a MkBufferListC from netHdl or null if invalid… → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]netHdlhandle former exported with MkBufferListHandleGet
Returns
the required handle or null if netHdl is invalid

int bfl.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkBufferListC useable for external storage → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe 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: jvmkkernel::MkBufferListC::Instances

The head-instance is the last instance created.

MkBufferListC bfl.Next()

top get next instance from linked-list of MkBufferListS type → API: jvmkkernel::MkBufferListC::Next

MkBufferListC bfl.Prev()

top get previous instance from linked-list of MkBufferListS type → API: jvmkkernel::MkBufferListC::Prev

MkBufferListC CLASS MISC

MkBufferListC - Misc class functions …

[static] MkBufferListC MkBufferListC.GetNull()

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

MkBufferListC TOR

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

[constructor,static] MkBufferListC MkBufferListC.Create(?int size = 0?)

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

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

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

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

top Constructs a MkBufferListC instance with an other MkBufferListC OR a list of arguments (only in NON C) → API: jvmkkernel::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(String tlsName, ?boolean resetB = true?)

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

class BFLT implements MqServiceIF {
public void Callback(MqContextC ctx) {
MkBufferListC bfl = MkBufferListC.CreateTLS("perfserver-BFLT" );
while (ReadItemExists()) {
bfl.AppendBUF(ReadBUF());
}
SendSTART();
var size = bfl.Size();
for (int i=0; i<size; i++) {
SendBUF(bfl.IndexGet(i));
};
SendRETURN();
}
}

Example from LibSq3LiteRpcClient.tcl callback dealing the temporary TLS data

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

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

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

  $myCb {*}$args $valL $colL
}
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]tlsNameAn per-thread unique name (string) to identify the reuse-able instance-storage. if tlsName is null or "" than a null is returned
[in]resetBshould 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

[destructor] bfl.Delete()

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

There are two different ways to delete an instance:

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

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

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

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

MkBufferListC APPEND

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

bfl.AppendBUF(MkBufferC val)

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
[in]valthe PRIMITIVE TYPE object data to append
Attention
After the insert the buffer is owed by the buf object -> do not free val.

bfl.AppendG(long val)

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

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

MkBufferListC bfl.AppendLA(MkBufferListC args)

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

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

MkBufferListC bfl.AppendLP(MkBufferListC addBufL, ?int position = -1?)

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

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

bfl.AppendStringR(String val)

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

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

bfl.AppendUP(MkBufferC addBuf, ?int position = -1?)

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

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

bfl.AppendTT(byte val)

top

The BufferListAppendTT provide a single function for every PRIMITIVE TYPE

attributereturncommand

C-API :

bfl.AppendI8(byte val)MkBufferListAppendI8_RT
bfl.AppendI16(short val)MkBufferListAppendI16_RT
bfl.AppendI32(int val)MkBufferListAppendI32_RT
bfl.AppendI64(long val)MkBufferListAppendI64_RT
bfl.AppendSTR(String val)MkBufferListAppendSTR_RT
bfl.AppendBIN(byte[] val)MkBufferListAppendBIN_RT
bfl.AppendBOL(boolean val)MkBufferListAppendBOL_RT
bfl.AppendFLT(float val)MkBufferListAppendFLT_RT
bfl.AppendDBL(double val)

MkBufferListAppendDBL_RT

append a native PRIMITIVE TYPE object to a MkBufferListC

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

boolean bfl.CheckOption(String opt, ?boolean onlyFirst = false?)

top search for boolean option in MkBufferListS list and return MK_BOL value … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on or null
[in]optFind opt string in the MkBufferListC
[in]onlyFirstStop after first item was found

MkBufferC bfl.CheckOptionBUF(String opt, ?MkBufferC defval = null?, ?boolean onlyFirst = true?)

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on or null
[in]optFind opt string in the MkBufferListC
[in]defvalThe value used if opt was not found
[in]onlyFirstIf more than one opt is available, return only the first (true [DEFAULT]) or the last (false)
[out]val_outIf opt is found, return the argument from opt otherwise defval
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Attention
  • If val_out is null an error is returned.
  • If the opt is found but no opt_argument than a error is returned.
  • If the opt is found, the opt and the opt_argument are deleted from the MkBufferListC.
  • If the defval is returned only a copy of the defval is returned and not the original defval.
  • If defval is null than an empty MkBufferC is returned.
  • (do not free) The memory of the out/return value belongs to the called jvmkkernel function and therefore never becomes null for a non-error result.
    For details on the out/return value, see: MkKernel_Storage_C_API.

bfl.CheckOptionTT(String opt, ?byte defval = 0?, ?boolean onlyFirst = true?)

top

The BufferListCheckOptionTT provide a single function for every PRIMITIVE TYPE

attributereturncommand

C-API :

bytebfl.CheckOptionI8(String opt, ?byte defval = 0?, ?boolean onlyFirst = true?)MkBufferListCheckOptionI8_RT
shortbfl.CheckOptionI16(String opt, ?short defval = 0?, ?boolean onlyFirst = true?)MkBufferListCheckOptionI16_RT
intbfl.CheckOptionI32(String opt, ?int defval = 0?, ?boolean onlyFirst = true?)MkBufferListCheckOptionI32_RT
longbfl.CheckOptionI64(String opt, ?long defval = 0?, ?boolean onlyFirst = true?)MkBufferListCheckOptionI64_RT
Stringbfl.CheckOptionSTR(String opt, ?String defval = ""?, ?boolean onlyFirst = true?)MkBufferListCheckOptionSTR_RT
booleanbfl.CheckOptionBOL(String opt, ?boolean defval = false?, ?boolean onlyFirst = true?)MkBufferListCheckOptionBOL_RT
floatbfl.CheckOptionFLT(String opt, ?float defval = 0?, ?boolean onlyFirst = true?)MkBufferListCheckOptionFLT_RT
doublebfl.CheckOptionDBL(String opt, ?double defval = 0?, ?boolean onlyFirst = true?)

MkBufferListCheckOptionDBL_RT

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on or null
[in]optFind opt string in the MkBufferListC
[in]defvalThe value used if opt was not found
[in]onlyFirstIf more than one opt is available, return only the first (true [DEFAULT]) or the last (false)
[out]val_outIf opt is found, return the argument from opt otherwise defval
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Attention
  • If val_out is null an error is returned.
  • If the opt is found but no opt_argument than a error is returned.
  • If the opt is found, the opt and the opt_argument are deleted from the MkBufferListC.
  • If the defval is returned only a copy of the defval is returned and not the original defval.

MkBufferListC INDEX

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

bfl.IndexDelete(int index, ?int numitems = 1?, ?boolean doDelete = true?)

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
numitemsdelete number of items
doDeleteif doDelete == true delete the MkBufferC object, associated with the index, too
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

MkBufferC bfl.IndexGet(int index)

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
[out]val_outthe MkBufferC to return
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 null first.
3. it is an error if index is not available.
See also
BufferListIndexGetBUF

MkBufferC bfl.IndexGetBUF(int index)

top get the index element from MkBufferListC ... if not available… create it. … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
Returns
the MkBufferC requested
See also
BufferListIndexGet

String bfl.IndexGetSTR(int index)

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

for details please refer to BufferListIndexGetBUF.

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
Returns
the string requested or an EMPTY-STRING on error

bfl.IndexSet(int index, MkBufferC buf)

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

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

top set the index element from MkBufferListC ... if not available… createspace … → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
[in]bufthe MkBufferS instance to work on

bfl.IndexSetSTR(int index, String str)

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

for details please refer to BufferListIndexGetBUF

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

MkBufferC bfl.IndexExtract(?int index = 0?)

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

If the index is not available, this is an error

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
[in]indexan integer index to access an object in an array by position, start=0, end=-1
[out]val_outthe MkBuffer64S object to return
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 null first.
See also
BufferListDelete

MkBufferListC LOG

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

bfl.Log(?MkObjectC fmtobj = null?, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

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

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

bfl.LogS(?String varname = "bfl"?, ?MkObjectC fmtobj = null?, ?String callfunc = null?)

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

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

bfl.LogSS(?String varname = "bfl"?, ?MkObjectC fmtobj = null?, ?String callfunc = null?)

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

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

bfl.LogSSS(?String varname = "bfl"?, ?MkObjectC fmtobj = null?, ?String callfunc = null?)

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

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

MkBufferListC MISC

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

[constructor,static] MkBufferListC MkBufferListC.FileGlob(String pattern_match)

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

to.Move(MkBufferListC from)

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

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

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

bfl.Copy(MkBufferListC src)

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

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

MkBufferListC bfl.PositionMerge(MkBufferListC source, int position)

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

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

int bfl.Cmp(MkBufferListC bfl2)

top compare two buffer-list … → API: jvmkkernel::MkBufferListC::Cmp

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

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

bfl.Reserve(int num)

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

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

MkBufferListC bfl.Reset()

top reset a MkBufferListC object … → API: jvmkkernel::MkBufferListC::Reset

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

int bfl.SearchC(String str, ?int len = -1?, ?int startindex = 0?)

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
strthe string to search for
lenthe length of str or -1 to calulate the length with strlen
startindexstart searching in buf from index startindex
Returns
The index of the str found or -1 if not found. The return value can be used as startindex of following calls to BufferListSearchC

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

while ((startindex = MkBufferListSearchC (buf, str, strlen(str), startindex)) != -1) {
...
}
#define MkBufferListSearchC(...)
Attention
The size of str have to be at least 4 bytes

int bfl.Size()

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

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

MkBufferListC bfl.Sort()

top sort a MkBufferListC … → API: jvmkkernel::MkBufferListC::Sort

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

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe MkBufferListS instance to work on
Returns
the required buffer or a null on error
Attention
(do not free) The memory of the out/return value belongs to the called jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

List<Object> bfl.ToList()

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]bflthe 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 jvmkkernel 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 jvmkkernel 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 jvmkkernel into the error-handling-code of the target Java.

Example from Filter6.java use MqContextErrorCatch to convert a Java error into a jvmkkernel error

  public static void main(String[] argv) {
    MqContextC srv = MqFactoryC.Add(Filter6.class).New();
    try {
      srv.LinkCreate(argv);
      srv.ProcessEvent(MqWaitOnEventE.FOREVER);
    } catch (Throwable e) {
      srv.ErrorCatch(e);
    } finally {
      srv.Exit();
    }
  }

MkExceptionC

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

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

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

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

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

Attention

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

          var VAL = ReadBUF();
          mycl = new Client();
          mycl.LinkCreate(ConfigGetStartAs());
          int PID = (int) mycl.Send("W", "GPID@I");
          int RET=0;
          SysKill(PID,9);
          for (int i = 0; i < 3; i++) {
            try {
              RET = (int) mycl.Send("W", "ECOI:U@I", VAL);
            } catch (MkExceptionC ex) {
              var err = mycl.ErrorCatch(ex);
              if (err.IsSOCKET()) {
                err.Reset();
                mycl.LinkConnect();
                continue;
              } else {
                err.Raise();
              }
            }
            break;
          }
          SendSTART();
          SendI32(RET);
Returns
the result of the check, true or false
Parameters
[in]exceptionthe exception object from Java, if null the global exception object is used

MkErrorC CLASS

NAVI: top, up

MkErrorC CLASS EXPORT

HandleResolve Handle-Resolve-Slot - return a MkErrorC from netHdl or null if invalid…
HandleGet

Handle-Get-Slot - returns a export-hdl to the MkErrorC useable for external storage

MkErrorC CLASS INTROSPECTION

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

get previous instance from linked-list of MkErrorS type

MkErrorC CLASS MISC

GetNull

Null-Slot - return a MkErrorC typed NULL instance …

MkErrorC CLASS DETAILS

C-API: MkErrorC_Class_C_API - MkErrorC - define the class …

MkErrorC CLASS EXPORT

MkErrorC - Export class functions …

[static] MkErrorC MkErrorC.HandleResolve(int netHdl)

top Handle-Resolve-Slot - return a MkErrorC from netHdl or null if invalid… → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]netHdlhandle former exported with MkErrorHandleGet
Returns
the required handle or null if netHdl is invalid

int err.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkErrorC useable for external storage → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe 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: jvmkkernel::MkErrorC::Instances

The head-instance is the last instance created.

MkErrorC err.Next()

top get next instance from linked-list of MkErrorS type → API: jvmkkernel::MkErrorC::Next

MkErrorC err.Prev()

top get previous instance from linked-list of MkErrorS type → API: jvmkkernel::MkErrorC::Prev

MkErrorC CLASS MISC

MkErrorC - Misc class functions …

[static] MkErrorC MkErrorC.GetNull()

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

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

int err.GetNum()

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

long err.GetSize()

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

String err.GetText()

top get the MkErrorS::text … → API: jvmkkernel::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(?MkObjectC errfmt = null?, ?String callfunc = null?, ?int errnum = -1?, String message)

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

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

err.AppendC(String message)

top append the message to the MkErrorS::text … → API: jvmkkernel::MkErrorC::AppendC

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]messagethe 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: jvmkkernel::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.java create and send an background-error message

  public void BgError () {
    MqContextC master = SlaveGetMaster();
    if (master != null) {
      MkErrorC err = master.ErrorFORMAT().NoRaise();
      err.SetC (err.GetText(), "BGERROR", err.GetNum());
      master.SendERROR ();
    }
  }
Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe 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 jvmkkernel error into an programming-language-error and raise afterwards. … → API: jvmkkernel::MkErrorC::Raise

If ther is no jvmkkernel-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_jv_ErrorCatch "ErrorCatch" \ref doc_mk_jv_ErrorReset "ErrorReset"

err.SetC(String message, ?String callfunc = null?, ?int errnum = -1?)

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

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

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

MkErrorC SIGNAL

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

boolean err.IsABORT()

top check on ABORT signal … → API: jvmkkernel::MkErrorC::IsABORT

boolean err.IsEXIT()

top check on APPLICATION-EXIT error … → API: jvmkkernel::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/java/Filter4.java example

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

if (MkErrorCheckI (MqSendEND_AND_WAIT (ctx, "TOKS", MK_TIMEOUT_USER))) {
}
#define MkErrorCheckI(err)
#define MkErrorReset_1X(x)
#define MkErrorIsEXIT_0E()
@ MK_TIMEOUT_USER
request the user defined timeout value from the –timeout configuration value …

boolean err.IsSOCKET()

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

boolean err.IsTIMEOUT()

top check on TIMEOUT error … → API: jvmkkernel::MkErrorC::IsTIMEOUT

err.SetABORT(?String detail = "UNKNOWN"?, ?String callfunc = null?)

top send the ABORT signal to the calling stack… → API: jvmkkernel::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(MkErrorE code)

top set the MkErrorS::code value … → API: jvmkkernel::MkErrorC::SetCode

err.SetCONTINUE()

top signal end of processing in an MqMqEventIF callback … → API: jvmkkernel::MkErrorC::SetCONTINUE

err.SetEXIT(?String callfunc = null?)

top finish the current callback, return to toplevel and MqExit the application … → API: jvmkkernel::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(?String detail = "UNKNOWN"?, ?String callfunc = null?)

top create SOCKET-DOWN error … → API: jvmkkernel::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: jvmkkernel::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(?MkObjectC fmtobj = null?)

top system-error-format - format and return the default-error … → API: jvmkkernel::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 null. The next error-message will be formated as usual and than be raised as error. The default-error will be modified.

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

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

[static] MkErrorC MkErrorC.IGNORE()

top ignore-system-error - ignore the next error … → API: jvmkkernel::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: jvmkkernel::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(?Throwable exception = null?, ?String callfunc = null?)

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

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

Example from Bug3.java catch an error using MkErrorC err.Catch(?Throwable exception = null?, ?String callfunc = null?)

    } catch (Throwable e) {
      MkErrorC.DEFAULT().Catch(e).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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errthe MkErrorS instance to work on - the default-error is automatically created on startup. (NULL allowed)
[in]exceptionthe exception object from Java, if null the global exception object is used
[in]callfunca user-defined postfix to identify the calling function or the environment (default=name-of-function)
Returns
the ErrorDEFAULT initialized with exception value
See also
ObjectErrorCatch ErrorRaise ErrorReset

err.Log(?MkObjectC fmtobj = null?, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

top log the error to MkLogFileC (default: stderr) … → API: jvmkkernel::MkObjectC::Log

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

err.Println()

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

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

err.Reset(?String callfunc = null?, ?int callline = -1?, ?boolean force = false?)

top This function clears the err and resets to MK_OK … → API: jvmkkernel::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(?String callfunc = null?, ?String callfile = null?, ?int callline = -1?)

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

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

err.StackFormat(?String callfunc = null?, ?String callfile = null?, ?int callline = -1?)

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

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

String inst.ToString()

top String-Slot - returns the string representation of the inst … → API: jvmkkernel::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]mkrtthe 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 jvmkkernel function and therefore never becomes null for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MkLogFileC

MkLogFileC CLASS

Export MkLogFileC - Export class functions …
Introspection MkLogFileC - Introspection class functions …
Misc

MkLogFileC - Misc class functions …

MkLogFileC TOR

Open open the log-file in append mode …
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.

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 null if invalid…
HandleGet

Handle-Get-Slot - returns a export-hdl to the MkLogFileC useable for external storage

MkLogFileC CLASS INTROSPECTION

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

get previous instance from linked-list of MkLogFileS type

MkLogFileC CLASS MISC

GetNull

Null-Slot - return a MkLogFileC typed NULL instance …

MkLogFileC CLASS DETAILS

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

MkLogFileC CLASS EXPORT

MkLogFileC - Export class functions …

[static] MkLogFileC MkLogFileC.HandleResolve(int netHdl)

top Handle-Resolve-Slot - return a MkLogFileC from netHdl or null if invalid… → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]netHdlhandle former exported with MkLogFileHandleGet
Returns
the required handle or null if netHdl is invalid

int lfl.HandleGet()

top Handle-Get-Slot - returns a export-hdl to the MkLogFileC useable for external storage → API: jvmkkernel::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]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]lflthe 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: jvmkkernel::MkLogFileC::Instances

The head-instance is the last instance created.

MkLogFileC lfl.Next()

top get next instance from linked-list of MkLogFileS type → API: jvmkkernel::MkLogFileC::Next

MkLogFileC lfl.Prev()

top get previous instance from linked-list of MkLogFileS type → API: jvmkkernel::MkLogFileC::Prev

MkLogFileC CLASS MISC

MkLogFileC - Misc class functions …

[static] MkLogFileC MkLogFileC.GetNull()

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

MkLogFileC TOR

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

[constructor,static] MkLogFileC MkLogFileC.Open(?MkObjectC errfmt = null?, String file)

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

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]errfmta managed object used to identify and format the error-message
[in]filethe filename to open
[out]lfh_outreturns
Returns
The newly created MkLogFileC instance, the instance is owned by the caller
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Attention
on error the lfh_out is set to null

[destructor] lfh.Close()

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

There are two different ways to delete an instance:

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

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]lflthe MkLogFileS instance to work on
[out]file_outthe log-file to return
Exceptions
MkExceptionC→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

lfl.WriteC(String text)

top write to log-file … → API: jvmkkernel::MkLogFileC::WriteC

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]lflthe MkLogFileS instance to work on
[in]textthe 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 jvmkkernel 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:

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 jvmkkernel technology.
the runtime provide the following features
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_jv_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] int MkRuntimeC.GetDebug()

top get the MkRuntimeS::debug value … → API: jvmkkernel::MkRuntimeC::GetDebug

[static] MkErrorE MkRuntimeC.GetErrorCode()

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

[static] boolean MkRuntimeC.GetIsSilent()

top get the MkRuntimeS::isSilent value … → API: jvmkkernel::MkRuntimeC::GetIsSilent

[static] String MkRuntimeC.GetLogfile()

top get the MkRuntimeS::logfile value … → API: jvmkkernel::MkRuntimeC::GetLogfile

Attention
the string is owned by jvmkkernel -> do not free !!

[static] MkRuntimeC.SetDebug(int dbg)

top set the MkRuntimeS::debug value … → API: jvmkkernel::MkRuntimeC::SetDebug

[static] MkRuntimeC.SetIsSilent(boolean silent)

top set the MkRuntimeS::isSilent value … → API: jvmkkernel::MkRuntimeC::SetIsSilent

[static] MkRuntimeC.SetLogfile(String logfile)

top set the MkRuntimeS::logfile value and cleanup old value … → API: jvmkkernel::MkRuntimeC::SetLogfile

Parameters
[in]mkrtthe MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]logfilefilename, "stdout" or "stderr", default = "stderr" for null or ""

MkRuntimeC INFO

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

rt.Log(?MkObjectC fmtobj = null?, ?int debug = 0?, ?String callfunc = null?, ?int lvl = 0?)

top log the MkRuntimeC … → API: jvmkkernel::MkObjectC::Log

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

BINARY OBJECT

No special binary-object is used. All binary-data is available as Java byte[].


EXAMPLES

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

class BUF2 implements MqServiceIF {
  public void Callback(MqContextC ctx) {
    ctx.SendSTART();

    for (int i=0; i<3; i++) {
      MkBufferC buf = ctx.ReadBUF();
      ctx.SendSTR(Character.toString(buf.GetType1()));
      ctx.SendBUF(buf);
    }

    ctx.SendRETURN();
  }
}

SEE ALSO

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

KEYWORDS

Java, unix, socket, message, msgque