A library to connect things, run a server and integrate an application.
The rbmqmsgque package is the implementation of the Programming-Language-Micro-Kernel (PLMK) into the target-language Ruby.
require 'rbmqmsgque'
The rbmqmsgque package is a composition of multiple classes defining the Programming-Language-Micro-Kernel (PLMK) :
object | description |
---|---|
RbMsgque::MqMsgque | the namespace with all rbmqmsgque specific definitions |
RbMsgque::MqMsgque.Attribute | the interface to access the package specific attribute |
RbMsgque::MqMsgque::LcClassC.Attribute | the interface to access the class specific attribute |
Instance.Attribute | the interface to access the instance specific attribute |
To access all features without RbMsgque::MqMsgque prefix use:
include RbMsgque::MqMsgque
RUBYLIB
have to include the directory.RUBYLIB A colon-separated list of directories that are added to Ruby's library load path ("$:"). Directories from this environment variable are searched before the standard load path is searched. e.g.: RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
C-API: MQ_C_API - theLink - a API to link multiple package-items together to act as one application …
The theLink project is an infrastructure that allows multiple package-items to be linked together to act as one application.
To link, you need to distribute the work from one package-item to another package-item and wait for an answer or not.
The package-item can be a thread, a separate local process that is started by fork or spawn, or even a network of multiple services on multiple hosts.
The package-item can be written in any language that is supported by the Programming-Language-Micro-Kernel (PLMK) support.
It even supports running multiple programming languages in a single piece of software.
Supported Languages are: (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO)
The package-item is connected to one another via a pipe or a socket and is based on packages which are sent from one package-item to another package-item and back.
theLink is responsible for:
The LibMsgque library is separted into three programming-layers:
C-API: MqConfigS::cfg - add libconfig configuration file …
A config-file is used to add configuration-values to a libmqmsgque-application using a structured text-file.
A service-callback and "programming" is not supported. To "programm and modify" something use a scripting language like tcl or python.
libconfig is used to parse a config-file using the application … --config fileName …
option.
The following restrictions apply to the --config
option.
--config
option is parsed groupname : { ... }
( ":" or "=" is allowed ) MyClient … --XXX … --config YYY … --ZZZ …
MyClient
: XXX < YYY < ZZZ MyClient --AAA … --config BBB --CCC … @ Filter3 --name otto --DDD … @ MyServer --EEE …
application | groupname | option-parsing-order |
---|---|---|
MyClient | MyClient | AAA < BBB < CCC |
Filter3 | otto | DDD < BBB |
MyServer | MyServer | EEE < BBB |
--name
or --prefix
option from DDD
or EEE
change the group read from the config-file --config
option--config
option overwrite the options from the config-file groupname : { … filter : [ … ] }
) config-file-option define the server to start in a pipe and have to be an array of strings starting with the application-executable OR the factory-identifer 1. Example from MyClient.config
→ filter-pipeline with last server start in debug mode
2. Example from libconfig.test
→ filter-pipeline with last server connect by tcp/ip
MqMsgque SETUP | |||
Cleanup | cleanup rbmqmsgque internal memory … | ||
Setup | setup rbmqmsgque internal memory … | ||
MqMsgque ENUM | |||
enum MqWaitOnEventE | wait for an event? … | ||
enum MqStatusIsEF | Information about how the context was created. | ||
enum MqStartE | User preferences on HOWTO start a new entity. | ||
enum MqSlaveE | predefined slave-id for well known slaves … | ||
enum MqIdentE | identify the application using prefix (default) or factory … | ||
MqMsgque HELP | |||
Help | write rbmqmsgque specific user-help to stderr | ||
HelpMsgque | return a page with the usage of all rbmqmsgque specific options | ||
MqMsgque INIT | |||
InitGetArg0 | get the process startup-prefix argument | ||
InitResetArg0 | Reset the process-startup-prefix argument to an empty list … | ||
InitSetArg0 | set the process startup-prefix argument to bfl |
C-API: MqMsgque_C_API - MqMsgque PACKAGE - the package is the toplevel structure of the rbmqmsgque …
The rbmqmsgque package is loaded with:
require 'rbmqmsgque'
and is a composition of one or more package-item and exact one package-main.
The rbmqmsgque package add the following classes into MkObjectC_C_API :
Object | C-Short | Description |
---|---|---|
MqContextC | MQ_CTX | MqContextC - the class known as ctx or context is the application-handle of the application-server and also the main data-handle … |
MqDumpC | MQ_DMP | MqDumpC - the class known as dmp or dump is used to export a rbmqmsgque data package as binary … |
MqFactoryC | MQ_FCT | MqFactoryC - the class known as fct or factory is used to provide an interface to create one or more new MqContextC … |
The rbmqmsgque package add the following types into MkObjectC_C_API :
ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType) | |- ABSTRACT: MqCtxTypeC_TT (TypeType = type of a Type) | | | |- MqContextC_T | |- ABSTRACT: MkSuperTypeSTT (TypeType = type of a Type) | |- MqFactoryST, MqDumpST
C-API: MqMsgque_Setup_C_API - MqMsgque PACKAGE - setup und cleanup the rbmqmsgque …
For details about MqSetup and MqCleanup usage refer to MkKernel_Setup_libmkkernel_C_API
(static) MqMsgque.Cleanup()
top cleanup rbmqmsgque internal memory … → API: rb_mqmsgque_MqMsgque_Cleanup
MkCleanup can only be called once and will be ignored if not called in the same thread as MqSetup. after a call to MqSetup the call to MkCleanup is possible again.
(static) MqMsgque.Setup()
top setup rbmqmsgque internal memory … → API: rb_mqmsgque_MqMsgque_Setup
MqSetup can only be called once, additional call's will be ignored until a MqCleanup is called.
C-API: MqMsgque_Enum_C_API - MqMsgque PACKAGE - enum definition …
read more at: MkKernel_Enum_C_API
top identify the application using prefix (default) or factory … → API: rb_mqmsgque_MqIdentE
(static) MqIdentE MqMsgque.IdentE_FromInt(value:int32)
top return the MqIdentE from integer … → API: rb_mqmsgque_MqMsgque_IdentE_FromInt
(static) int32 MqMsgque.IdentE_ToInt(value:MqIdentE)
top return the MqIdentE as integer … → API: rb_mqmsgque_MqMsgque_IdentE_ToInt
(static) string MqMsgque.IdentE_ToString(value:MqIdentE)
top return the MqIdentE as string … → API: rb_mqmsgque_MqMsgque_IdentE_ToString
top predefined slave-id for well known slaves … → API: rb_mqmsgque_MqSlaveE
(static) MqSlaveE MqMsgque.SlaveE_FromInt(value:int32)
top return the MqSlaveE from integer … → API: rb_mqmsgque_MqMsgque_SlaveE_FromInt
(static) int32 MqMsgque.SlaveE_ToInt(value:MqSlaveE)
top return the MqSlaveE as integer … → API: rb_mqmsgque_MqMsgque_SlaveE_ToInt
(static) string MqMsgque.SlaveE_ToString(value:MqSlaveE)
top return the MqSlaveE as string … → API: rb_mqmsgque_MqMsgque_SlaveE_ToString
top User preferences on HOWTO start a new entity. → API: rb_mqmsgque_MqStartE
(static) MqStartE MqMsgque.StartE_FromInt(value:int32)
top return the MqStartE from integer … → API: rb_mqmsgque_MqMsgque_StartE_FromInt
(static) int32 MqMsgque.StartE_ToInt(value:MqStartE)
top return the MqStartE as integer … → API: rb_mqmsgque_MqMsgque_StartE_ToInt
(static) string MqMsgque.StartE_ToString(value:MqStartE)
top return the MqStartE as string … → API: rb_mqmsgque_MqMsgque_StartE_ToString
top Information about how the context was created. → API: rb_mqmsgque_MqStatusIsEF
(static) MqStatusIsEF MqMsgque.StatusIsEF_FromInt(value:int32)
top return the MqStatusIsEF from integer … → API: rb_mqmsgque_MqMsgque_StatusIsEF_FromInt
(static) int32 MqMsgque.StatusIsEF_ToInt(value:MqStatusIsEF)
top return the MqStatusIsEF as integer … → API: rb_mqmsgque_MqMsgque_StatusIsEF_ToInt
(static) string MqMsgque.StatusIsEF_ToString(value:MqStatusIsEF)
top return the MqStatusIsEF as string … → API: rb_mqmsgque_MqMsgque_StatusIsEF_ToString
top wait for an event? … → API: rb_mqmsgque_MqWaitOnEventE
(static) MqWaitOnEventE MqMsgque.WaitOnEventE_FromInt(value:int32)
top return the MqWaitOnEventE from integer … → API: rb_mqmsgque_MqMsgque_WaitOnEventE_FromInt
(static) int32 MqMsgque.WaitOnEventE_ToInt(value:MqWaitOnEventE)
top return the MqWaitOnEventE as integer … → API: rb_mqmsgque_MqMsgque_WaitOnEventE_ToInt
(static) string MqMsgque.WaitOnEventE_ToString(value:MqWaitOnEventE)
top return the MqWaitOnEventE as string … → API: rb_mqmsgque_MqMsgque_WaitOnEventE_ToString
C-API: MqMsgque_Help_C_API - MqMsgque PACKAGE - access to a qualified help-message …
(static) string MqMsgque.Help(tool:string)
top write rbmqmsgque specific user-help to stderr → API: rb_mqmsgque_MqMsgque_Help
tool | the name of the tool (e.g. argv[0]) or NULL. |
If tool != NULL, the function will display a header like:
tool [ARGUMENT]... syntax: aclient [OPTION]... @ tool [OPTION]... @...
on the help page.
(static) string MqMsgque.HelpMsgque()
top return a page with the usage of all rbmqmsgque specific options → API: rb_mqmsgque_MqMsgque_HelpMsgque
C-API: MqMsgque_Init_C_API - MqMsgque PACKAGE - initialize the MqContextC startup and/or external-object-link …
(static) MkBufferListC MqMsgque.InitGetArg0()
top get the process startup-prefix argument → API: rb_mqmsgque_MqMsgque_InitGetArg0
(static) MkBufferListC MqMsgque.InitResetArg0()
top Reset the process-startup-prefix argument to an empty list … → API: rb_mqmsgque_MqMsgque_InitResetArg0
The startup-prefix have to be the name of the executable, found in the PATH
environment variable, and additional arguments like the script name or the required startup options. The startup-prefix is used for two different purpose:
MqStartAs
"--spawn" command-line option."... @ SELF ..."
with "... @ startup-prefix ..."
at LinkCreate.Every use of this function will free the data of the previous startup-prefix. By default the startup-prefix is set during application startup by rbmqmsgque and have not to be initialized again.
Example from server.rb
→ initialize the startup-prefix with the data read from service-args
def INIT SendSTART() InitSetArg0(ReadALL()) SendRETURN() end
(static) MqMsgque.InitSetArg0(?bfl:MkBufferListC...=nil?)
top set the process startup-prefix argument to bfl → API: rb_mqmsgque_MqMsgque_InitSetArg0
The startup-prefix is the argument(s) required to start the application… this is minimal the binary-path for binaries (same as as used on command-line) or the interpreter+scriptFile for scripts.
[in] | bfl | the object will be merged into the startup-prefix, afterwords the bfl is empty and can be deleted |
MqContextC CLASS | |||
Export | MqContextC - Export class functions … | ||
Introspection | MqContextC - Introspection class functions … | ||
Misc | MqContextC - Misc class functions … | ||
MqContextC TOR | |||
Create | create and initialize the MqContextC ... | ||
new | create and initialize the MqContextC ... | ||
Delete | Destructor - delete a MqContextC instance … | ||
MqContextC CLASS API | MqContextC - access data related to the factory-type of the object … | ||
MqContextC CONFIG API | |||
Get | MqContextC - various function to 'get' the configuration-data from a context … | ||
Interface | MqContextC - various function to setup a interface for the context … | ||
Misc | MqContextC - various function to do 'misc' configuration … | ||
Set | MqContextC - various function to 'set' the configuration-data in a context … | ||
MqContextC ENV API | MqContextC - protect and restore the service-environment … | ||
MqContextC ERROR API | MqContextC - move and copy an error from a context … | ||
MqContextC HIGH API | MqContextC - User friendly replacement for the MqContextC_SendApi_C_API and the MqContextC_ReadApi_C_API … | ||
MqContextC LINK API | MqContextC - setup and manage a client-server-link … | ||
MqContextC LOG API | MqContextC - log the output to a string or a MkLogFileC … | ||
MqContextC MISC API | MqContextC - various functions to work on a context … | ||
MqContextC PROXY API | MqContextC - copy data from the read-data-package of the sourceCtx to the send-data-package of the targetCtx | ||
MqContextC READ API | |||
Atom | MqContextC - read a single-data-item outof a read-data-package … | ||
Block | MqContextC - read a block-of-data outof a read-data-package … | ||
Misc | MqContextC - various functions to work on a read-data-package … | ||
MqContextC ROUTE API | MqContextC - setup and manage a routing-link … | ||
MqContextC SEND API | |||
Atom | MqContextC - append a native PRIMITIVE TYPE value to the send-data-package … | ||
Basics | MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service … | ||
Block | MqContextC - a wrapper to send a list-block or a transaction-block … | ||
Return | MqContextC - finish the send-data-block on the server and optional return the results. … | ||
MqContextC SERVICE API | MqContextC - create and manage a service … | ||
MqContextC SLAVE API | MqContextC - create and manage a slave context … | ||
MqContextC STORAGE API | MqContextC - setup and manage a storage used to persist data-packages … |
C-API: MqContextC_C_API - MqContextC - the class known as ctx or context is the application-handle of the application-server and also the main data-handle …
The context is the package-item with the required features and created by the implementation-layer-programmer. The context can be a client or a server.
The client-context-creation is triggerd by the software-workflow on demand. The client is calling the MqLinkCreate to create a connection to the server using the connection-arguments to specify the target.
The life-cycle of a client is:
ContextCreate | create and initialize the MqContextC ... |
LinkCreate | make ctx to a parent-context and setup a new client-server-link … |
SendTT | MqContextC - append a native PRIMITIVE TYPE value to the send-data-package … |
ReadTT | read a PRIMITIVE TYPE from the read-data-package … |
LinkDelete | close the client-server-link … |
ContextDelete | Destructor - delete a MqContextC instance … |
Exit | delete the context and exit the current process or thread … |
The server-context-creation is always triggerd by the MqLinkCreate command of the client. The server is usually using a factory-constructor to call the MqContextCreate and finally to call the MqContextDelete.
The server-context is fully under control of the client.
The life-cycle of a server is:
SETUP | define a class and add the setup/cleanup code |
IServerSetup | define the server-setup-interface (callback) used on startup … |
ServiceCreate | create a link between a service-token and a service-callback … |
IServerCleanup | define the server-cleanup-interface (callback) used on cleanup … |
ServiceDelete | delete a service. … |
STARTUP | define the factory and start the listener |
FactoryAdd | add a new MqFactoryC identified by factory-identifier and defined by factory-constructor … |
FactoryNew | create a new MqContextC from a MqFactoryC … |
LinkCreate | make ctx to a parent-context and setup a new client-server-link … |
ProcessEvent | enter the event-loop and wait for an incoming service-request. … |
WORK | process the service-calls and exit on end |
ReadTT | read a PRIMITIVE TYPE from the read-data-package … |
SendTT | MqContextC - append a native PRIMITIVE TYPE value to the send-data-package … |
Exit | delete the context and exit the current process or thread … |
command | alias |
---|---|
(constructor,static) MqContextC MqContextC.Create(?tmpl:MqContextC=nil?) | rbmsgque.MqMsgque.MqContextC(?tmpl:MqContextC=None?) |
(destructor) ctx.Delete() | ctx = nil |
HandleResolve | Handle-Resolve-Slot - return a MqContextC from netHdl or nil if invalid… | ||
HandleGet | Handle-Get-Slot - returns a export-hdl to the MqContextC useable for external storage |
MqContextC CLASS INTROSPECTION
Instances | get head-instance from linked-list of MqContextS type … | ||
Next | get next instance from linked-list of MqContextS type | ||
Prev | get previous instance from linked-list of MqContextS type |
GetNull | Null-Slot - return a MqContextC typed |
C-API: MqContextC_Class_C_API - MqContextC - define the class …
MqContextC - Export class functions …
(static) MqContextC MqContextC.HandleResolve(netHdl:MK_HDL)
top Handle-Resolve-Slot - return a MqContextC from netHdl or nil if invalid… → API: rb_mqmsgque_MqContextC_HandleResolve
The MqContextHandleResolve undo the MqContextHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | netHdl | handle former exported with MqContextHandleGet |
MK_HDL ctx.HandleGet()
top Handle-Get-Slot - returns a export-hdl to the MqContextC useable for external storage → API: rb_mkkernel_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 MqContextHandleResolve.
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.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MqContextC - Introspection class functions …
(static) MqContextC MqContextC.Instances()
top get head-instance from linked-list of MqContextS type … → API: rb_mqmsgque_MqContextC_Instances
The head-instance is the last instance created.
MqContextC ctx.Next()
top get next instance from linked-list of MqContextS type → API: rb_mqmsgque_MqContextC_Next
MqContextC ctx.Prev()
top get previous instance from linked-list of MqContextS type → API: rb_mqmsgque_MqContextC_Prev
MqContextC - Misc class functions …
(static) MqContextC MqContextC.GetNull()
top Null-Slot - return a MqContextC typed NULL
instance … → API: rb_mqmsgque_MqContextC_GetNull
C-API: MqContextC_TOR_C_API - MqContextC - various functions to create, initialize and destroy a context …
(constructor,static) MqContextC MqContextC.Create(?tmpl:MqContextC=nil?)
top create and initialize the MqContextC ... → API: rb_mqmsgque_MqContextC_Create
This function is used to create a single new context… primary on the client. to create multiple new context on a server… a MqFactoryC is used.
The new instance belongs to the caller and may have to be released if necessary. A manual release using ContextDelete is always possible, but the instance can no longer be used afterwards.
Example from MyClient.rb
→ create a context using the static rbmqmsgque CTOR
require "rbmqmsgque" include RbMsgque::MqMsgque ctx = MqContextC.new begin ctx.ConfigSetName("MyClient") ctx.LinkCreate(ARGV) ctx.SendSTART() ctx.SendSTR "Hello" ctx.SendEND_AND_WAIT("HLWO") puts ctx.ReadSTR() rescue Exception => ex ctx.ErrorCatch(ex) ensure ctx.Exit() end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | type | type type of the object like MqContextC_T or a new type created with MkTypeDup2. (default: nil, reuse the MkTypeSTT from tmpl or use MqContextC_T if tmpl = nil) |
[in] | tmpl | an other context-data-structure used as template to initialize the configuration data. This template is used for a child to get the configuration data from the parent. (default: nil, create an initial context) |
(constructor,static) MqContextC MqContextC.new(?tmpl:MqContextC=nil?)
top create and initialize the MqContextC ... → API: rb_mqmsgque_MqContextC_new
This function is used to create a single new context… primary on the client. to create multiple new context on a server… a MqFactoryC is used.
The new instance belongs to the caller and may have to be released if necessary. A manual release using ContextDelete is always possible, but the instance can no longer be used afterwards.
Example from MyClient.rb
→ create a context using the static rbmqmsgque CTOR
require "rbmqmsgque" include RbMsgque::MqMsgque ctx = MqContextC.new begin ctx.ConfigSetName("MyClient") ctx.LinkCreate(ARGV) ctx.SendSTART() ctx.SendSTR "Hello" ctx.SendEND_AND_WAIT("HLWO") puts ctx.ReadSTR() rescue Exception => ex ctx.ErrorCatch(ex) ensure ctx.Exit() end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | type | type type of the object like MqContextC_T or a new type created with MkTypeDup2. (default: nil, reuse the MkTypeSTT from tmpl or use MqContextC_T if tmpl = nil) |
[in] | tmpl | an other context-data-structure used as template to initialize the configuration data. This template is used for a child to get the configuration data from the parent. (default: nil, create an initial context) |
(destructor) ctx.Delete()
top Destructor - delete a MqContextC instance … → API: MqContextDelete_RT
Shutdown the client-server-link, free the memory and set the ctx to nil. The context can not be reused.
Example from MyClient2.rb
→ delete a application-context using the rbmqmsgque DTOR
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
ClassFactoryGet | get the MqFactoryC used by the MqContextC | ||
ClassFactorySet | link the MqContextC to a new MqFactoryC | ||
ClassIdentGet | get the application-identification … | ||
ClassIdentSet | link the MqContextC to a new MqFactoryC identified by ident | ||
ClassOriginalIdentGet | get the MqFactoryS::originalIdent from the MqContextC |
C-API: MqContextC_ClassApi_C_API - MqContextC - access data related to the factory-type of the object …
The type of an object is related to the MqFactoryC. The factory decide which class a new created object has. The factory has two identifiers:
The relevance of the MqContextC CLASS API based type system, provided by MqFactoryC, decreased with the rise of the MANAGED OBJECT technology.
The MqContextC CLASS API based type system has more influence for target-languages without reflection, like C or C++.
The factory is something like a constructor but only support the application-context MqContextC .
The MqContextC ROUTE API using the MqClassIdentGet from MqFactoryC to identify an application from remote.
MqFactoryC ctx.ClassFactoryGet()
top get the MqFactoryC used by the MqContextC → API: rb_mqmsgque_MqContextC_ClassFactoryGet
[in] | ctx | the MqContextC to extract the MqFactoryC from |
ctx.ClassFactorySet(item:MqFactoryC)
top link the MqContextC to a new MqFactoryC → API: rb_mqmsgque_MqContextC_ClassFactorySet
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextC to be linked with the MqFactoryC |
[in] | item | the MqFactoryC to link with |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
string ctx.ClassIdentGet()
top get the application-identification … → API: rb_mqmsgque_MqContextC_ClassIdentGet
[in] | ctx | the MqContextC to extract the ident from |
An application has TWO possible names:
The --ident-from prefix|factory value decide which on is used.
The application-identification is defined by MqConfigS::identFrom :
MqFactoryS::originalIdent | if ident == MQ_IDENT_FACTORY |
MqConfigS::prefix | if ident == MQ_IDENT_PREFIX (default) |
The MqFactoryS::originalIdent is the official name of the MqFactoryC and is defined by the application-programmer with MqFactoryAdd or MqFactoryDup2.
The MqConfigS::prefix is the official name of the MqContextC that startet first, usually the server-name, and is set by the application-user with --prefix string at startup or with the MqConfigSetPrefix at setup.
When the server starts, the MqClassIdentGet value is send from the server to the client and the client initializes the MqLinkS::targetIdent with this value. This value identifes the server from remote and is used by the MqContextC ROUTE API to select which server receive the routing-package.
The client usually get the factory and the idenfication from the: MqFactoryInitial.
Example: Change the factory-identifier of MqFactoryInitial to the value "TestClient" with:
C# | MqFactoryC.Get("initial").Dup2("TestClient").Initial() |
TCL | [[tclmsgque::MqFactoryC Get "initial"] Dup2 "TestClient"] Initial |
ctx.ClassIdentSet(ident:string)
top link the MqContextC to a new MqFactoryC identified by ident → API: rb_mqmsgque_MqContextC_ClassIdentSet
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextC to set the ident |
[in] | ident | the MqFactoryS::originalIdent to link with |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
string ctx.ClassOriginalIdentGet()
top get the MqFactoryS::originalIdent from the MqContextC → API: rb_mqmsgque_MqContextC_ClassOriginalIdentGet
[in] | ctx | the MqContextC to extract the original-ident from |
ConfigGetBuffersize | get the minimum of the read/send buffersize of the socket | ||
ConfigGetIdentFrom | get the MqConfigS::identFrom | ||
ConfigGetIoPipe | return the MqIoPipeConfigS | ||
ConfigGetIoTcp | get the configuration-data of the tcp-client-server-link … | ||
ConfigGetIoTcpL | get the configuration-data of the tcp-client-server-link as MkBufferListC … | ||
ConfigGetIoUds | return the MqIoUdsConfigS | ||
ConfigGetIsParent | does the context object is a parent ? An objext is a parent id the MqConfigS::parent attribute is nil | ||
ConfigGetIsServer | does the context object is a server ? | ||
ConfigGetIsString | does the context object is using the string-mode ? | ||
ConfigGetName | get the name of the context object | ||
ConfigGetPkgsize | get the maximun size of a BDY package | ||
ConfigGetPostfix | get the MqConfigS::postfix | ||
ConfigGetPrefix | get the MqConfigS::prefix | ||
ConfigGetStartAs | return the MqConfigS::startAs value | ||
ConfigGetStatusIs | return the MqContextS::statusIs value | ||
ConfigGetStorage | get the storage of the context object | ||
ConfigGetTimeout | get the timeout value of the context object | ||
ConfigSetConfigFile | set the config-file and parse for well-known config-items |
MqContextC CONFIG API INTERFACE
ConfigSetBgError | set the MqSetupS::BgError | ||
ConfigSetEvent | set the MqSetupS::Event | ||
ConfigSetServerCleanup | set the MqSetupS::ServerCleanup | ||
ConfigSetServerSetup | set the MqSetupS::ServerSetup |
ConfigReset | clean the MqContextS::config data |
ConfigCheckStartAs | check if MqConfigS::startAs can be set to data | ||
ConfigSetAllDebug | set the MkRuntimeS::debug value | ||
ConfigSetBuffersize | set the MqIoConfigS::buffersize value | ||
ConfigSetDaemon | start the server-context as daemon … | ||
ConfigSetIdentFrom | set the MqConfigS::identFrom value | ||
ConfigSetIgnoreExit | set the MqSetupS::ignoreExit value | ||
ConfigSetIoPipe | set the pipe configuration data … | ||
ConfigSetIoTcp | configure a context to use a tcp-client-server-link … | ||
ConfigSetIoTcpL | configure a context to use a tcp-client-server-link … | ||
ConfigSetIoUds | configure a context to use a uds-client-server-link … | ||
ConfigSetIsServer | set the MqSetupS::isServer value | ||
ConfigSetIsString | set the MqConfigS::native value 'S'string or 'L'owEndian or 'B'igEndian | ||
ConfigSetName | set the MqConfigS::dispname value and cleanup old value | ||
ConfigSetPkgsize | set the MqIoConfigS::pkgsize value | ||
ConfigSetPostfix | set the client-part (2) of the application-identifer MqConfigS::dispname … | ||
ConfigSetPrefix | set the server-part (1) of the application-identifer MqConfigS::dispname … | ||
ConfigSetStartAs | set the MqConfigS::startAs value | ||
ConfigSetStartAsString | set the MqConfigS::startAs value using string default , thread , fork or spawn | ||
ConfigSetStorage | set the Storage value and cleanup old value | ||
ConfigSetTimeout | set the MqIoConfigS::timeout value |
C-API: MqContextC_ConfigApi_C_API - MqContextC - various functions to config a context …
The configuration is done persistent using config-api functions or on link-setup using command-line-arguments.
set: ctx.ConfigSetConfigFile(filename:string)
add libconfig configuration file …
A config-file is used to add configuration-values to a libmqmsgque-application using a structured text-file.
A service-callback and "programming" is not supported. To "programm and modify" something use a scripting language like tcl or python.
libconfig is used to parse a config-file using the application … --config fileName …
option.
The following restrictions apply to the --config
option.
--config
option is parsed groupname : { ... }
( ":" or "=" is allowed ) MyClient … --XXX … --config YYY … --ZZZ …
MyClient
: XXX < YYY < ZZZ MyClient --AAA … --config BBB --CCC … @ Filter3 --name otto --DDD … @ MyServer --EEE …
application | groupname | option-parsing-order |
---|---|---|
MyClient | MyClient | AAA < BBB < CCC |
Filter3 | otto | DDD < BBB |
MyServer | MyServer | EEE < BBB |
--name
or --prefix
option from DDD
or EEE
change the group read from the config-file --config
option--config
option overwrite the options from the config-file groupname : { … filter : [ … ] }
) config-file-option define the server to start in a pipe and have to be an array of strings starting with the application-executable OR the factory-identifer 1. Example from MyClient.config
→ filter-pipeline with last server start in debug mode
2. Example from libconfig.test
→ filter-pipeline with last server connect by tcp/ip
attribute: MqConfigS::dispname, getter: MqContextC_ConfigGetName, setter: MqContextC_ConfigSetName
set the display-name of the context …
The display-name is used as:
C> (dispname) [2009-01-12:16-22-27] [4-0-sIoCheckArg]: option: io->com = PIPE
The dispname is initialized with:
ctx.ConfigSetName(data:string)
, ctx.ConfigSetPrefix(data:string)
, ctx.ConfigSetPostfix(data:string)
function prefix | postfix | dispname |
---|---|---|
client | -1-1 | client-1-1 |
ctx.ConfigSetName(data:string)
or --name stringattribute: MqConfigS::prefix, getter: MqContextC_ConfigGetPrefix, setter: MqContextC_ConfigSetPrefix
set the server-part (1) of the application-identifer MqConfigS::dispname …
The prefix is used for:
The prefix is initialize with:
ctx.ConfigSetPrefix(data:string)
or the ctx.ConfigSetName(data:string)
functionattribute: MqConfigS::postfix, getter: MqContextC_ConfigGetPostfix, setter: MqContextC_ConfigSetPostfix
set the client-part (2) of the application-identifer MqConfigS::dispname …
The postfix is used for:
The postfix is initialize with:
ctx.ConfigSetPostfix(data:string)
functionattribute: MqConfigS::storage, getter: MqContextC_ConfigGetStorage, setter: MqContextC_ConfigSetStorage
attribute: MqConfigS::identFrom, getter: MqContextC_ConfigGetIdentFrom, setter: MqContextC_ConfigSetIdentFrom
select how to identify the application from remote …
An application has TWO possible names:
The --ident-from prefix|factory value decide which on is used.
The application-identification is defined by MqConfigS::identFrom :
MqFactoryS::originalIdent | if ident == MQ_IDENT_FACTORY |
MqConfigS::prefix | if ident == MQ_IDENT_PREFIX (default) |
The MqFactoryS::originalIdent is the official name of the MqFactoryC and is defined by the application-programmer with MqFactoryAdd or MqFactoryDup2.
The MqConfigS::prefix is the official name of the MqContextC that startet first, usually the server-name, and is set by the application-user with --prefix string at startup or with the MqConfigSetPrefix at setup.
When the server starts, the MqClassIdentGet value is send from the server to the client and the client initializes the MqLinkS::targetIdent with this value. This value identifes the server from remote and is used by the MqContextC ROUTE API to select which server receive the routing-package.
The client usually get the factory and the idenfication from the: MqFactoryInitial.
Example: Change the factory-identifier of MqFactoryInitial to the value "TestClient" with:
C# | MqFactoryC.Get("initial").Dup2("TestClient").Initial() |
TCL | [[tclmsgque::MqFactoryC Get "initial"] Dup2 "TestClient"] Initial |
attribute: MqIoTcpConfigS, getter: MqContextC_ConfigGetIoTcp, setter: MqContextC_ConfigSetIoTcp
configure a context to use a tcp-client-server-link …
[in] | host | client: name of the remote interface (default: localhost) server: name of the local interface (default: listen on all interfaces) |
[in] | port | client: name of the remote port server: name of the local port |
[in] | myhost | client: name of the local interface |
[in] | myport | client: name of the local port |
attribute: MqIoUdsConfigS, getter: MqContextC_ConfigGetIoUds, setter: MqContextC_ConfigSetIoUds
configure a context to use a uds-client-server-link …
The uds-socket (http://en.wikipedia.org/wiki/Unix_domain_socket) is usually 50% faster than a local tcp communication but only available on UNIX.
[in] | file | name of a uds-socket-file (default: nil) |
attribute: MqIoPipeConfigS, getter: MqContextC_ConfigGetIoPipe, setter: MqContextC_ConfigSetIoPipe
configure a context to use a pipe-client-server-link …
The socket option is special because it is used only for internal purpose to submit the socket from the client to the server started as pipe by the client.
[in] | hdl | the file-descriptor-number (default: not set) |
attribute: MqConfigS::startAs, getter: MqContextC_ConfigGetStartAs, setter: MqContextC_ConfigSetStartAs
create a new application-context as thread, spawn or fork …
A new application-context is created if:
The allowed integer values for MqConfigS::startAs are:
(default: do not create a new application-context)
set: ctx.ConfigSetDaemon(pidfile:string)
This option is not available for rbmqmsgque.
attribute: MkRuntimeS::logfile, getter: MkRuntimeC_GetLogfile, setter: MkRuntimeC_SetLogfile
attribute: MkRuntimeS::isSilent, getter: MkRuntimeC_GetIsSilent, setter: MkRuntimeC_SetIsSilent
attribute: MkRuntimeS::debug, getter: MkRuntimeC_GetDebug, setter: MkRuntimeC_SetDebug
attribute: MqIoConfigS::buffersize, getter: MqContextC_ConfigGetBuffersize, setter: MqContextC_ConfigSetBuffersize
set the OS specific value for the socket-operation-buffer (default: OS specific)
attribute: MqIoConfigS::pkgsize, getter: MqContextC_ConfigGetPkgsize, setter: MqContextC_ConfigSetPkgsize
set maximum package size (default: 10 KiB)
attribute: MqIoConfigS::timeout, getter: MqContextC_ConfigGetTimeout, setter: MqContextC_ConfigSetTimeout
user defined timeout to terminate a blocking function call (default: 90 sec)
attribute: MqConfigS::native, getter: MqContextC_ConfigGetIsString, setter: MqContextC_ConfigSetIsString
define if data is string or little or big endian …
define the server-setup-interface (callback) used on startup …
This interface is used to configure a new server-context-link, like a constructor, and is called at the end of MqLinkCreate or MqLinkCreateChild. This interface is called for every new incoming connection request and is used to define context specific services using MqServiceCreate or to initialize context-specific variables. As side-effect this interface set MqSetupS::isServer to true.
IServerSetup
: callback signatureRead more about how to define a service-callback in theLink .
define the server-cleanup-interface (callback) used on cleanup …
This interface is used to cleanup an old server-context-link, like a destructor, and is called at the beginning of MqLinkDelete to free context-specific variables. As side-effect this interface set MqSetupS::isServer to true.
IServerCleanup
: callback signatureRead more about how to define a service-callback in theLink .
define the background-error-interface …
A background error is an error without a link to an application-context and happen if an MqSendEND call fails or if an other asynchronous task fails. if the interface is not defined the error is printed to stderr and the application continue to work. if the interface is defined the context is set to error and the callback is called to process this error. Inside the callback the error is available using ErrorGetNum and ErrorGetText and can be cleared using ErrorReset.
IBgError
: callback signatureRead more about how to define a service-callback in theLink .
Create a link to the calling tool event-handling queue …
Event-Handling is used to process tasks in the background to give the tool-user the feeling of a non-blocking application. For example Tcl using the event-handling to update the Tk user-interface while the application is waiting for data. The event handling function is called on idle-time and is designed for a very short function execution time. Do only one action per function call. This function will be called with a ~10000 usec interval to guarantee a parallel like execution.
example/LANG/Filter4.EXT
IEvent
: callback signatureRead more about how to define a service-callback in theLink .
C-API: MqContextC_ConfigApi_Get_C_API - MqContextC - various function to 'get' the configuration-data from a context …
int32 ctx.ConfigGetBuffersize()
top get the minimum of the read/send buffersize of the socket → API: rb_mqmsgque_MqContextC_ConfigGetBuffersize
[in] | ctx | the MqContextS instance to work on |
context.config.buffersize
(R/S) value MqIdentE ctx.ConfigGetIdentFrom()
top get the MqConfigS::identFrom → API: rb_mqmsgque_MqContextC_ConfigGetIdentFrom
[in] | ctx | the MqContextS instance to work on |
prefix
or factory int32 ctx.ConfigGetIoPipe()
top return the MqIoPipeConfigS → API: rb_mqmsgque_MqContextC_ConfigGetIoPipe
[in] | ctx | the MqContextS instance to work on |
{host:string port:string myhost:string myport:string} ctx.ConfigGetIoTcp()
top get the configuration-data of the tcp-client-server-link … → API: rb_mqmsgque_MqContextC_ConfigGetIoTcp
[in] | ctx | the MqContextS instance to work on |
[out] | host_out | client: name of the remote interface (default: localhost) server: name of the local interface (default: listen on all interfaces) |
[out] | port_out | client: name of the remote port server: name of the local port |
[out] | myhost_out | client: name of the local interface |
[out] | myport_out | client: name of the local port |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MkBufferListC ctx.ConfigGetIoTcpL()
top get the configuration-data of the tcp-client-server-link as MkBufferListC … → API: rb_mqmsgque_MqContextC_ConfigGetIoTcpL
host |
| ||||
port |
| ||||
myhost | name of the local interface | ||||
myport | name of the local port |
[in] | ctx | the MqContextS instance to work on |
[out] | vals_out | the contain host, port, myhost and myport data |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
string ctx.ConfigGetIoUds()
top return the MqIoUdsConfigS → API: rb_mqmsgque_MqContextC_ConfigGetIoUds
[in] | ctx | the MqContextS instance to work on |
context.config.io.uds.file
value bool ctx.ConfigGetIsParent()
top does the context object is a parent ? An objext is a parent id the MqConfigS::parent attribute is nil → API: rb_mqmsgque_MqContextC_ConfigGetIsParent
[in] | ctx | the MqContextS instance to work on |
(ctx->config.parent == NULL)
value bool ctx.ConfigGetIsServer()
top does the context object is a server ? → API: rb_mqmsgque_MqContextC_ConfigGetIsServer
[in] | ctx | the MqContextS instance to work on |
(ctx->setup.isServer == true)
value bool ctx.ConfigGetIsString()
top does the context object is using the string-mode ? → API: rb_mqmsgque_MqContextC_ConfigGetIsString
[in] | ctx | the MqContextS instance to work on |
(ctx->config.native == 'S')
value string ctx.ConfigGetName()
top get the name of the context object → API: rb_mqmsgque_MqContextC_ConfigGetName
[in] | ctx | the MqContextS instance to work on |
context.config.name
value int32 ctx.ConfigGetPkgsize()
top get the maximun size of a BDY package → API: rb_mqmsgque_MqContextC_ConfigGetPkgsize
[in] | ctx | the MqContextS instance to work on |
context.config.pkgsize
(R/S) value string ctx.ConfigGetPostfix()
top get the MqConfigS::postfix → API: rb_mqmsgque_MqContextC_ConfigGetPostfix
[in] | ctx | the MqContextS instance to work on |
string ctx.ConfigGetPrefix()
top get the MqConfigS::prefix → API: rb_mqmsgque_MqContextC_ConfigGetPrefix
[in] | ctx | the MqContextS instance to work on |
MqStartE ctx.ConfigGetStartAs()
top return the MqConfigS::startAs value → API: rb_mqmsgque_MqContextC_ConfigGetStartAs
MqStatusIsEF ctx.ConfigGetStatusIs()
top return the MqContextS::statusIs value → API: rb_mqmsgque_MqContextC_ConfigGetStatusIs
string ctx.ConfigGetStorage()
top get the storage of the context object → API: rb_mqmsgque_MqContextC_ConfigGetStorage
[in] | ctx | the MqContextS instance to work on |
context.config.storage
value MkTimeoutE|int32 ctx.ConfigGetTimeout()
top get the timeout value of the context object → API: rb_mqmsgque_MqContextC_ConfigGetTimeout
[in] | ctx | the MqContextS instance to work on |
context.config.timeout
value ctx.ConfigSetConfigFile(filename:string)
top set the config-file and parse for well-known config-items → API: rb_mqmsgque_MqContextC_ConfigSetConfigFile
Read more at MqConfigS::cfg
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | filename | name of the config-file for input |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
C-API: MqContextC_ConfigApi_Interface_C_API - MqContextC - various function to setup a interface for the context …
The "Setup"-Callback is special because this callback have to be callable by the server child and/or the slave context.
To distinguish the server child and slave the following functions are used:
"if"
clause and the child/parent check"if"
clause and the master/slave check
"if"
clause and the server/child check ctx.ConfigSetBgError(?callback:callable=nil?)
top set the MqSetupS::BgError → API: rb_mqmsgque_MqContextC_ConfigSetBgError
define the background-error-interface …
A background error is an error without a link to an application-context and happen if an MqSendEND call fails or if an other asynchronous task fails. if the interface is not defined the error is printed to stderr and the application continue to work. if the interface is defined the context is set to error and the callback is called to process this error. Inside the callback the error is available using ErrorGetNum and ErrorGetText and can be cleared using ErrorReset.
IBgError
: callback signatureThis function register a callback and is used to configure the application for a specific task.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fCall | function called with callback as argument to work on an specific task. |
[in] | callback | argument for fCall, for a target-language this is the target-language-callback-hdl. |
[in] | fFree | cleanup the callback, called at the destruction of ctx. |
[in] | fCopy | copy-constructor of the callback, used if the ctx is used to initialize an other newctx. |
ctx.ConfigSetEvent(?callback:callable=nil?)
top set the MqSetupS::Event → API: rb_mqmsgque_MqContextC_ConfigSetEvent
Create a link to the calling tool event-handling queue …
Event-Handling is used to process tasks in the background to give the tool-user the feeling of a non-blocking application. For example Tcl using the event-handling to update the Tk user-interface while the application is waiting for data. The event handling function is called on idle-time and is designed for a very short function execution time. Do only one action per function call. This function will be called with a ~10000 usec interval to guarantee a parallel like execution.
example/LANG/Filter4.EXT
IEvent
: callback signatureThis function register a callback and is used to configure the application for a specific task.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fCall | function called with callback as argument to work on an specific task. |
[in] | callback | argument for fCall, for a target-language this is the target-language-callback-hdl. |
[in] | fFree | cleanup the callback, called at the destruction of ctx. |
[in] | fCopy | copy-constructor of the callback, used if the ctx is used to initialize an other newctx. |
ctx.ConfigSetServerCleanup(?callback:callable=nil?)
top set the MqSetupS::ServerCleanup → API: rb_mqmsgque_MqContextC_ConfigSetServerCleanup
define the server-cleanup-interface (callback) used on cleanup …
This interface is used to cleanup an old server-context-link, like a destructor, and is called at the beginning of MqLinkDelete to free context-specific variables. As side-effect this interface set MqSetupS::isServer to true.
IServerCleanup
: callback signatureThis function register a callback and is used to configure the application for a specific task.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fCall | function called with callback as argument to work on an specific task. |
[in] | callback | argument for fCall, for a target-language this is the target-language-callback-hdl. |
[in] | fFree | cleanup the callback, called at the destruction of ctx. |
[in] | fCopy | copy-constructor of the callback, used if the ctx is used to initialize an other newctx. |
ctx.ConfigSetServerSetup(?callback:callable=nil?)
top set the MqSetupS::ServerSetup → API: rb_mqmsgque_MqContextC_ConfigSetServerSetup
define the server-cleanup-interface (callback) used on cleanup …
This interface is used to cleanup an old server-context-link, like a destructor, and is called at the beginning of MqLinkDelete to free context-specific variables. As side-effect this interface set MqSetupS::isServer to true.
IServerCleanup
: callback signatureThis function register a callback and is used to configure the application for a specific task.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fCall | function called with callback as argument to work on an specific task. |
[in] | callback | argument for fCall, for a target-language this is the target-language-callback-hdl. |
[in] | fFree | cleanup the callback, called at the destruction of ctx. |
[in] | fCopy | copy-constructor of the callback, used if the ctx is used to initialize an other newctx. |
C-API: MqContextC_ConfigApi_Misc_C_API - MqContextC - various function to do 'misc' configuration …
ctx.ConfigReset()
top clean the MqContextS::config data → API: rb_mqmsgque_MqContextC_ConfigReset
C-API: MqContextC_ConfigApi_Set_C_API - MqContextC - various function to 'set' the configuration-data in a context …
bool ctx.ConfigCheckStartAs(data:MqStartE)
top check if MqConfigS::startAs can be set to data → API: rb_mqmsgque_MqContextC_ConfigCheckStartAs
ctx.ConfigSetAllDebug(data:int32)
top set the MkRuntimeS::debug value → API: rb_mqmsgque_MqContextC_ConfigSetAllDebug
set all childs and all slaves and the link target parter… too
ctx.ConfigSetBuffersize(data:int32)
top set the MqIoConfigS::buffersize value → API: rb_mqmsgque_MqContextC_ConfigSetBuffersize
ctx.ConfigSetDaemon(pidfile:string)
top start the server-context as daemon … → API: rb_mqmsgque_MqContextC_ConfigSetDaemon
A daemon is a server-process without any link to the parent-process. A daemon-process has closed all default IO (e.g stdout, stdin, stderr) and forked into the background. (default: no daemon)
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | pidfile | write the PID of the daemon into this file (default: NULL, do not start as daemon) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ConfigSetIdentFrom(data:MqIdentE)
top set the MqConfigS::identFrom value → API: rb_mqmsgque_MqContextC_ConfigSetIdentFrom
ctx.ConfigSetIgnoreExit(data:bool)
top set the MqSetupS::ignoreExit value → API: rb_mqmsgque_MqContextC_ConfigSetIgnoreExit
ctx.ConfigSetIoPipe(fh:int32)
top set the pipe configuration data … → API: rb_mqmsgque_MqContextC_ConfigSetIoPipe
This is configuration option is only useful for a (x)inetd setup to use the stdin (socket=0) as send/recv communication socket
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fh | the name of the known socket |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ConfigSetIoTcp(?host:string="nil"?, ?port:string="nil"?, ?myhost:string="nil"?, ?myport:string="nil"?)
top configure a context to use a tcp-client-server-link … → API: rb_mqmsgque_MqContextC_ConfigSetIoTcp
[in] | host | client: name of the remote interface (default: localhost) server: name of the local interface (default: listen on all interfaces) |
[in] | port | client: name of the remote port server: name of the local port |
[in] | myhost | client: name of the local interface |
[in] | myport | client: name of the local port |
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ConfigSetIoTcpL(vals:MkBufferListC)
top configure a context to use a tcp-client-server-link … → API: rb_mqmsgque_MqContextC_ConfigSetIoTcpL
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | vals | a list with host, port, myhost, myport |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ConfigSetIoUds(file:string)
top configure a context to use a uds-client-server-link … → API: rb_mqmsgque_MqContextC_ConfigSetIoUds
The uds-socket (http://en.wikipedia.org/wiki/Unix_domain_socket) is usually 50% faster than a local tcp communication but only available on UNIX.
[in] | file | name of a uds-socket-file (default: nil) |
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ConfigSetIsServer(data:bool)
top set the MqSetupS::isServer value → API: rb_mqmsgque_MqContextC_ConfigSetIsServer
ctx.ConfigSetIsString(data:bool)
top set the MqConfigS::native value 'S'string or 'L'owEndian or 'B'igEndian → API: rb_mqmsgque_MqContextC_ConfigSetIsString
ctx.ConfigSetName(data:string)
top set the MqConfigS::dispname value and cleanup old value → API: rb_mqmsgque_MqContextC_ConfigSetName
ctx.ConfigSetPkgsize(data:int32)
top set the MqIoConfigS::pkgsize value → API: rb_mqmsgque_MqContextC_ConfigSetPkgsize
ctx.ConfigSetPostfix(data:string)
top set the client-part (2) of the application-identifer MqConfigS::dispname … → API: rb_mqmsgque_MqContextC_ConfigSetPostfix
The postfix is used for:
The postfix is initialize with:
ctx.ConfigSetPostfix(data:string)
function ctx.ConfigSetPrefix(data:string)
top set the server-part (1) of the application-identifer MqConfigS::dispname … → API: rb_mqmsgque_MqContextC_ConfigSetPrefix
The prefix is used for:
The prefix is initialize with:
ctx.ConfigSetPrefix(data:string)
or the ctx.ConfigSetName(data:string)
function ctx.ConfigSetStartAs(data:MqStartE)
top set the MqConfigS::startAs value → API: rb_mqmsgque_MqContextC_ConfigSetStartAs
ctx.ConfigSetStartAsString(data:string)
top set the MqConfigS::startAs value using string default
, thread
, fork
or spawn
→ API: rb_mqmsgque_MqContextC_ConfigSetStartAsString
ctx.ConfigSetStorage(data:string)
top set the Storage value and cleanup old value → API: rb_mqmsgque_MqContextC_ConfigSetStorage
ctx.ConfigSetTimeout(data:MkTimeoutE|int32)
top set the MqIoConfigS::timeout value → API: rb_mqmsgque_MqContextC_ConfigSetTimeout
EnvProtect | protect the service-environment | ||
EnvRestore | restore the service-environment |
C-API: MqContextC_EnvApi_C_API - MqContextC - protect and restore the service-environment …
The "Env" style functions are used to secure the service-environment (defined in MqEnvS)
and is required.. under special conditions... to proper answer the original service call at the
end of the service-processing.
By default rbmqmsgque guarantee the proper management of the environment on behalf of the user.
Under normal conditions the user don't need these functions.
The folllowing design-goals were defined:
come-in == come-out
The two design-goals from above are in conflict and the both functions MqEnvProtect and MqEnvRestore are used to solve this conflict.
Example from server.rb
→ protect the environment and import from database
# PROTECT the original service-call EnvProtect() # OVERWRITE the original service-call with data from the database @dump.Import(self) read = ReadALL() # RESTORE the original service-call EnvRestore() # ANSWER the original service-call Send("R", "L", read);
ctx.EnvProtect()
top protect the service-environment → API: rb_mqmsgque_MqContextC_EnvProtect
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
ctx.EnvRestore()
top restore the service-environment → API: rb_mqmsgque_MqContextC_EnvRestore
[in] | ctx | the MqContextS instance to work on |
ErrorCopy | copy a MkErrorS from the sourceCtx to the targetCtx … | ||
ErrorFORMAT | helper used to access MkErrorDEFAULT from MqContextC | ||
ErrorMove | move a MkErrorS from the sourceCtx to the targetCtx … |
C-API: MqContextC_ErrorApi_C_API - MqContextC - move and copy an error from a context …
MkErrorE targetCtx.ErrorCopy(sourceCtx:MqContextC)
top copy a MkErrorS from the sourceCtx to the targetCtx … → API: rb_mqmsgque_MqContextC_ErrorCopy
In rbmqmsgque the a MkRuntimeC is only one error-object per thread but this error-object has also addiitional attributes to identify the source of the error. In addition the rbmqmsgque has also an extended-error-object MqErrorS which also has error-specific-attributes. The MqContextErrorCopy is used to copy an error frome sourceCtx to targetCtx and keep the additional attributes in sync.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
targetCtx | the MqContextC object and the target of the error | |
sourceCtx | the MqContextC object and the source of the error |
MkErrorC fmtobj.ErrorFORMAT()
top helper used to access MkErrorDEFAULT from MqContextC → API: rb_mqmsgque_MqContextC_ErrorFORMAT
MkErrorE targetCtx.ErrorMove(sourceCtx:MqContextC)
top move a MkErrorS from the sourceCtx to the targetCtx … → API: rb_mqmsgque_MqContextC_ErrorMove
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
targetCtx | the MqContextC object and the target of the error | |
sourceCtx | the MqContextC object and the source of the error and cleared |
Send | user friendly replacement for the MqContextC_SendApi_C_API … |
C-API: MqContextC_HighApi_C_API - MqContextC - User friendly replacement for the MqContextC_SendApi_C_API and the MqContextC_ReadApi_C_API …
User Friendly mean, replacing many lines of code by a single line of code.
The basic idea is, to use a format-signature to identify the additional command-line-arguments (args…).
The pseudo syntax is:
The following parts from the MqContextC_SendApi_C_API will be replaced by the MqContextC_HighApi_C_API
API Function | Usage |
---|---|
MqSendSTART | -> start a service call or a answer |
SendATOM | -> write a single argument into the data-package |
SendEND | -> send the service-call to the receiver |
ReadATOM | -> read a single argument from the data-package |
SendRETURN | -> answer a service call |
The replacement is defined by two parts, a High_CALL_SIGNATURE and a High_TOKEN_SIGNATURE. Both parts are strings and descripe a type or an action of a vararg argument.
Example: a typical code replacement in C looks like
and replaces the following commands...
The Call-Signature is a string of call-signature-char (CFC) starting with "E", "W", "C", "S" or "R" followed optional with "t"
CFC | Required | Reference | call-args | Default | Usage |
---|---|---|---|---|---|
E | yes | once | no | yes | MqSendEND |
W | yes | once | no | no | MqSendEND_AND_WAIT |
C | yes | once | function or service | no | MqSendEND_AND_CALLBACK |
S | yes | once | function or service | no | MqSendEND_AND_SUB |
T | yes | once | service-ident | no | MqSendEND_AND_TRANSACTION |
R | yes | once | no | no | MqSendRETURN |
t | no | W,S,T | seconds | MK_TIMEOUT_USER | set the TIMEOUT |
"service-ident : send-signature @ read-signature"
and is used to identify the target-service and the required arguments.
[:] and the send-signature.ASC | MkTypeE | Usage | Number of arguments required |
---|---|---|---|
"Y" | MK_I8 | MkBufferAtomU.I8 | 1 |
"O" | MK_BOL | MkBufferAtomU.BOL | 1 |
"S" | MK_I16 | MkBufferAtomU.I16 | 1 |
"I" | MK_I32 | MkBufferAtomU.I32 | 1 |
"F" | MK_FLT | MkBufferAtomU.FLT | 1 |
"W" | MK_I64 | MkBufferAtomU.I64 | 1 |
"D" | MK_DBL | MkBufferAtomU.DBL | 1 |
"G" | MK_LONG | 32bit=I, 64bit=W | 1 |
"B" | MK_BIN | MkBufferU.B | 1 -> MkBinaryR reference |
"C" | MK_STR | MkBufferU.C | 1 |
"U" | MK_BUF | MkBufferC . | 1 -> typeless Buffer able to hold every kind of data |
"L" | MK_BFL | MkBufferListC . | 1 -> list of MkBufferC . |
"." | MK_BUF | MkBufferC . | 1 -> READ ONLY - like 'U' but return the Buffer-Value and not the MkBufferC . |
"*" | MK_BFL | MkBufferListC . | 1 -> READ ONLY - like 'L' but collect ALL remaining data as ONE MkBufferListC . |
"[" | MqSendL_START | 0 -> Start of List | |
"]" | MqSendL_END | 0 -> End of List | |
"(" | MqSendT_START | 0 -> Start of Transaction Object, only as FIRST parameter | |
")" | MqSendT_END | 0 -> End of Transaction Object, only ONE supported | |
":" | END of SERVICE-IDENT | * -> next SEND_SIGNATURE | |
"@" | END of SEND-SIGN. | * -> next READ-SIGNATURE |
Example from server.rb
→ in a service-call send the server-configuratien back to the client
def CNFG SendSTART() SendBOL(ConfigGetIsServer()) SendBOL(LinkIsParent()) SendBOL(SlaveIs()) SendBOL(ConfigGetIsString()) SendBOL(MkRuntimeC.GetIsSilent()) SendBOL(LinkIsConnected()) SendSTR(ConfigGetName()) SendI32(MkRuntimeC.GetDebug()) SendI32(LinkGetCtxId()) SendSTR(ServiceTokenGet()) SendRETURN() end
ctx.Send(cstr:string, args:args...)
top user friendly replacement for the MqContextC_SendApi_C_API … → API: MqSend_RT
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | cstr | the High_CALL_SIGNATURE |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
LinkConnect | re-connect a client-server-link after a server crash or a network downtime … | ||
LinkCreate | make ctx to a parent-context and setup a new client-server-link … | ||
LinkCreateChild | make a context to a child-context on-top of an existing parent-client-server-link … | ||
LinkDelete | close the client-server-link … | ||
LinkGetCtxId | get an identifier which is unique per parent-or-child-context … | ||
LinkGetParent | get the initial parent-context from a client/server link … | ||
LinkGetTargetIdent | get the ident of the link-target … | ||
LinkIsConnected | is the context connected? … | ||
LinkIsParent | is the context a parent-context? … | ||
LinkShutdown | shutdown the communication with a server |
C-API: MqContextC_LinkApi_C_API - MqContextC - setup and manage a client-server-link …
The client-server-link connect two context, a client-parent-context and a server-parent-context. The link can be local (connect two context on the same host) or can be remote (connect two context on different hosts). On-Top the parent-context multiple child-context are allowed.
!on remote host! !on local host! server1---------x x----------server2 | | | | | child-context-1 child-context-2 | | | | | server parent-context-1-----x x-----parent-context-2 | | (MqConfigS::server) (example: MqConfigS::server --fork --uds … --file …) | | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | (--tcp) (--pipe, --uds, --tcp) | | parent-context-1-----x x-----parent-context-2 | | | | client | child-context-1 child-context-2 | | | | | x------------x--------client-------x-------------x !on local host!
Definition of a "client-context"
Definition of a "server-context"
Definition of a "parent-context"
Definition of a "child-context"
ctx.LinkConnect()
top re-connect a client-server-link after a server crash or a network downtime … → API: rb_mqmsgque_MqContextC_LinkConnect
Do nothing if the client-server-link is already connected. This function is only useful in an event-function (IEvent) if the link-disconnect (ErrorIsEXIT) is ignored (ErrorReset). Read more from the: /example/rb/Filter4.rb
example.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.LinkCreate(?args:MkBufferListC...=nil?)
top make ctx to a parent-context and setup a new client-server-link … → API: rb_mqmsgque_MqContextC_LinkCreate
The goal of the MqLinkCreate is to setup a link to a new server-context on the SERVER.
The link is created with MqIoComE to a server started with MqStartE.
The argument args is a list of command-line-arguments to configure the client-server-link including the @ item to add server-command-line-arguments.
The following special-keyword as first argument after @ is recognized:
"@ SELF arg1…"
will be "@ executable factory-name arg1…"
"@ WORKER arg1…"
will be "@ executable arg1…"
The executable is defined by (static) MqMsgque.InitSetArg0(?bfl:MkBufferListC...=nil?)
and will be automatical set for a non C / C++ language.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | args | command-line-arguments to configure the client-server-link |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.LinkCreateChild(parent:MqContextC, ?args:MkBufferListC...=nil?)
top make a context to a child-context on-top of an existing parent-client-server-link … → API: rb_mqmsgque_MqContextC_LinkCreateChild
A child is using the same process or thread as the parent but a different namespace. With a different namespace a child is able to act on different services on the shared server.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | parent | the parent-context defined with MqLinkCreate |
[in] | args | command-line-arguments to configure the client-server-link without the "@" item. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.LinkDelete()
top close the client-server-link … → API: rb_mqmsgque_MqContextC_LinkDelete
On a client the context will be set to not-connected and the function MqLinkIsConnected will return false. On a server the context will be deleted but only if MqSetupS::ignoreExit is not set to true. If the link is already not-connected nothing will happen.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
int32 ctx.LinkGetCtxId()
top get an identifier which is unique per parent-or-child-context … → API: rb_mqmsgque_MqContextC_LinkGetCtxId
The context-identifier is a number and is used in the protocol to link a data-package to a context-pointer. This is necessary because the communication interface is shared between the parent-context and the child-context. This number is unique.
[in] | ctx | the MqContextS instance to work on |
MqContextC ctx.LinkGetParent()
top get the initial parent-context from a client/server link … → API: rb_mqmsgque_MqContextC_LinkGetParent
[in] | ctx | the MqContextS instance to work on |
string ctx.LinkGetTargetIdent()
top get the ident of the link-target … → API: rb_mqmsgque_MqContextC_LinkGetTargetIdent
This function is only useful if the link is up and running.
[in] | ctx | the MqContextS instance to work on |
bool ctx.LinkIsConnected()
top is the context connected? … → API: rb_mqmsgque_MqContextC_LinkIsConnected
A context is connected if the MqLinkCreate command was successful. A context is not connected if:
[in] | ctx | the MqContextS instance to work on |
bool ctx.LinkIsParent()
top is the context a parent-context? … → API: rb_mqmsgque_MqContextC_LinkIsParent
A context is a parent-context if it was created with MqLinkCreate
[in] | ctx | the MqContextS instance to work on |
ctx.LinkShutdown()
top shutdown the communication with a server → API: rb_mqmsgque_MqContextC_LinkShutdown
The following tasks are performend:
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
Log | log the MqContextC … | ||
LogConfig | log the MqContextC part MqConfigS … | ||
LogEnv | log the MqContextC part MqEnvS … | ||
LogLink | log the MqContextC part MqLinkS … | ||
LogSetup | log the MqContextC part MqSetupS … | ||
LogShort | log the MqContextC with less info then MqContextLog … | ||
LogType | log the MqContextC part MkTypeS … | ||
LogParentOrChild | is ctx a PARENT or a CHILD ? … | ||
LogServerOrClient | is ctx a SERVER or a CLIENT ? … |
C-API: MqContextC_LogApi_C_API - MqContextC - log the output to a string or a MkLogFileC …
Logging is an important part of the debugging and validation task.
The logging target is set with MkRuntimeSetLogfile wich accepts a filename or the special token stdout or stderr.
Many logging functions have common parameters:
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
ctx.Log(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the MqContextC … → API: rb_mkkernel_MkObjectC_Log
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
ctx.LogConfig(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the MqContextC part MqConfigS … → API: rb_mqmsgque_MqContextC_LogConfig
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
ctx.LogEnv(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the MqContextC part MqEnvS … → API: rb_mqmsgque_MqContextC_LogEnv
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
ctx.LogLink(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the MqContextC part MqLinkS … → API: rb_mqmsgque_MqContextC_LogLink
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
ctx.LogSetup(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the MqContextC part MqSetupS … → API: rb_mqmsgque_MqContextC_LogSetup
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
ctx.LogShort(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?, ?label:string="nil"?)
top log the MqContextC with less info then MqContextLog … → API: rb_mqmsgque_MqContextC_LogShort
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | label | a string to identify a task or object |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
ctx.LogType(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the MqContextC part MkTypeS … → API: rb_mqmsgque_MqContextC_LogType
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
string ctx.LogParentOrChild()
top is ctx a PARENT or a CHILD ? … → API: rb_mqmsgque_MqContextC_LogParentOrChild
[in] | ctx | the MqContextS instance to work on |
string ctx.LogServerOrClient()
top is ctx a SERVER or a CLIENT ? … → API: rb_mqmsgque_MqContextC_LogServerOrClient
[in] | ctx | the MqContextS instance to work on |
GetBuffer | get the MqContextS::ctxbuf object | ||
ToString | String-Slot - returns the string representation of the inst … | ||
Exit | delete the context and exit the current process or thread … | ||
GetRoot | get the Root (toplevel initial context) | ||
ProcessEvent | enter the event-loop and wait for an incoming service-request. … |
C-API: MqContextC_MiscApi_C_API - MqContextC - various functions to work on a context …
MkBufferC ctx.GetBuffer()
top get the MqContextS::ctxbuf object → API: rb_mqmsgque_MqContextC_GetBuffer
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
context->ctxbuf
object string ctx.ToString()
top String-Slot - returns the string representation of the inst … → API: rb_mkkernel_MkObjectC_ToString
The string is a human-readable form of the data stored in the object.
ToString
function by default.[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
"MK_NULL"
on error ctx.Exit(?callfunc:string="MK_NULL"?, ?callfile:string="MK_NULL"?, ?callline:int32=-1?)
top delete the context and exit the current process or thread … → API: rb_mqmsgque_MqContextC_Exit
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | callfile | the name of the file the call take place (e.g. FILE) |
[in] | callline | the number of the line the call take place (e.g. LINE) |
To delete an application is a difficult task because the link-target have to be informed. This information is send as shutdown-event and finally as socket-exit after application-exit. This library tries to perform this two steps even if the default exit function is called. This is no problem because the second step (socket-exit) is enough to signal a link-down. It is not secure to depend only on socket-exit for application exit because sometimes the sockets stop working or the link-target does not get a socket-exit. For example the pipe-link on windows. The client can not exit and create a socket-exit error on the server because the server is still running without receiving a shutdown-event. A second argument for using the MqExit function is, that it can be used for process and thread exit. A thread, started by rbmqmsgque, does exit but the process continue to work. To make it short use MqExit to exit your application.
The following steps are performed:
MqContextC ctx.GetRoot()
top get the Root (toplevel initial context) → API: rb_mqmsgque_MqContextC_GetRoot
ctx.ProcessEvent(?wait:MqWaitOnEventE=NO?, ?timeout:MkTimeoutE|int32=DEFAULT?)
top enter the event-loop and wait for an incoming service-request. … → API: rb_mqmsgque_MqContextC_ProcessEvent
This function is used to enter the event-loop and start listen on open file-handles and to call IEvent on idle.
This function is mostly used on a server to enter the event-loop and wait for an incoming service request or on a client/server with all functions which exchange data like MqContextC SEND API, MqLinkConnect etc.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) | ||||||||||||
[in] | ctx | the MqContextS instance to work on | ||||||||||||
[in] | wait | the operation-mode used to define the behaviour, possible values are:
| ||||||||||||
[in] | timeout | in seconds until a timeout-error is raised, possible values are:
|
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ProxyForward | send the entire read-data-package-data to the link-target … | ||
ProxyItem | Copy a single-data-item from the sourceCtx to the targetCtx. |
C-API: MqContextC_ProxyApi_C_API - MqContextC - copy data from the read-data-package of the sourceCtx to the send-data-package of the targetCtx
The proxy-feature is used in a filter-setup to process-and-forward incoming data.
Example: A typical proxy-setup in pseudo C++ code
sourceCtx.ProxyForward(targetCtx:MqContextC, ?dump:MqDumpC=nil?, ?timeout:MkTimeoutE|int32=DEFAULT?)
top send the entire read-data-package-data to the link-target … → API: rb_mqmsgque_MqContextC_ProxyForward
The goal of this function is to link two context, typically a master and a slave (filter). This function is typically used in a service or and event callback to send the entire package and wait for the answer.
Example of a typical usage in pseudo c++
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | sourceCtx | the source of the copy |
[in,out] | targetCtx | the target of the copy |
[in] | dump | if not nil, the value is the source of the copy, dump is the return from MqDumpExport, |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=MK_TIMEOUT_USER ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
sourceCtx.ProxyItem(targetCtx:MqContextC)
top Copy a single-data-item from the sourceCtx to the targetCtx. → API: rb_mqmsgque_MqContextC_ProxyItem
MqContextC - copy data from the read-data-package of the sourceCtx to the send-data-package of the targetCtx
The proxy-feature is used in a filter-setup to process-and-forward incoming data.
Example: A typical proxy-setup in pseudo C++ code
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | sourceCtx | the source of the copy |
[in,out] | targetCtx | the target of the copy |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ReadTT | read a PRIMITIVE TYPE from the read-data-package … | ||
ReadALL | get a temporary MkBufferListC from all data in the read-data-package … | ||
ReadBFL | get a temporary MkBufferListC from next list-item in the read-data-package … | ||
ReadBinaryR | read a MkBinaryR from the read-data-package … | ||
ReadBUF | get a temporary MkBufferC from the read-data-package … | ||
ReadHDL | read the handle from the read-data-package | ||
ReadLIST | get all arguments as native list … | ||
ReadLONG | read the long native object from the read-data-package | ||
ReadNEXT | get the next argument as native object … | ||
ReadStringR | read a MkStringR from the read-data-package … |
ReadL_END | finish to extract a list-items from the read-data-package. … | ||
ReadL_START | start to extract a list-items from the read-data-package. … | ||
ReadT_END | finish to extract a longterm-transaction-item from the read-data-package. … | ||
ReadT_START | start to extract a longterm-transaction-item from the read-data-package. … |
ReadGetNextType | get the type (MkTypeE) of the next Item in the read-data-buffer or "0" if not available | ||
ReadGetNumItems | get the number of items left in the read-data-package … | ||
ReadItemExists | check if an item exists in the read-data-package … | ||
ReadUndo | undo the last MqContextC READ API function call … |
C-API: MqContextC_ReadApi_C_API - MqContextC - extract data from an incoming read-data-package …
A data-package is read in two different scenarios:
Reading data is a passive-task and the opposite of sending data, which is an active-task. Passive means that the reading process is triggered by an incoming-data-package and not by the software workflow or by the user.
There is a read function and some help functions for each basic type defined in MkBufferC .
Example from server.rb
→ read-safety: Make a nested service-call
def CSV1 # read the input-data from the CSV1-service-call # client → server inI = ReadI32() + 1 # call the CSV2-service at the client, wait 10sec for timeout # server → client → server retI = Send("Wt", 10, "CSV2:I@I", inI) + 1 # answer the CSV1-service-call with the result from the CSV2-service-call # server → client Send("R", "I", retI) end
C-API: MqContextC_ReadApi_Atom_C_API - MqContextC - read a single-data-item outof a read-data-package …
MkBufferListC ctx.ReadALL(?val_inout:MkBufferListC=nil?)
top get a temporary MkBufferListC from all data in the read-data-package … → API: rb_mqmsgque_MqContextC_ReadALL
If the val_inout is nil than a temporary MkBufferListC is returned. If the val_inout is not nil than the memory of the val_inout is reused.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_inout | the MkBufferListC - the storage of the input is reused |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MkBufferListC ctx.ReadBFL()
top get a temporary MkBufferListC from next list-item in the read-data-package … → API: rb_mqmsgque_MqContextC_ReadBFL
If the next item in the read-data-package is a list-item, (created with MqReadL_START and ctx.ReadL_END()
), only return this item. If the next item in the read-data-package is not a list-item than return an error. If you require all data in the read-data-package returned as single MkBufferListC than use MqReadALL.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | the MkBufferListC as return-value |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
binary ctx.ReadBinaryR()
top read a MkBinaryR from the read-data-package … → API: rb_mqmsgque_MqContextC_ReadBinaryR
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | the MkBinaryR to return |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MkBufferC ctx.ReadBUF()
top get a temporary MkBufferC from the read-data-package … → API: rb_mqmsgque_MqContextC_ReadBUF
Return a temporary-data-item from the read-data-package. The lifetime of the MkBufferC is only the current callback up to the next read operation in the same parent-context. This object is owned by RbMsgque::MqMsgque and must not be freed.
Example from server.rb
→ read and update a MkBufferC
# ReadBUF - Example, read a buffer-object and append a string buf = ReadBUF() buf.AppendSTR("- a really log text to overwrite the already allocated space") SendBUF(buf) SendI32(ReadI32()+1)
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | The out-value of type MkBufferC. 1) It is an error if the out-value is nil, 2. If there is an error, the out-value remains unchanged. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MK_HDL ctx.ReadHDL()
top read the handle from the read-data-package → API: rb_mqmsgque_MqContextC_ReadHDL
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | the handle-object to read |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
[list...] ctx.ReadLIST()
top get all arguments as native list … → API: MqReadLIST_RT
The MqReadLIST is a function what interacts with the Target-Programming-Language (TPL) list-object.
There is no guarantee that a list-object will be available. Therefore, this function is an add-on and will only be implemented when possible.
Example from example/tcl/server.tcl
→ start a WORKER using all arguments from the service-call.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | the native list as return |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
long ctx.ReadLONG()
top read the long native object from the read-data-package → API: rb_mqmsgque_MqContextC_ReadLONG
on 64bit use a MqReadI64 and on 32bit use a MqReadI32
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | the native long object to read |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
obj ctx.ReadNEXT()
top get the next argument as native object … → API: MqReadNEXT_RT
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | the native object as return |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
string ctx.ReadStringR()
top read a MkStringR from the read-data-package … → API: rb_mqmsgque_MqContextC_ReadStringR
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | the MkStringR to return |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ReadTT()
The ReadTT provide a single function for every PRIMITIVE TYPE
attribute | return | command | C-API : |
---|---|---|---|
int8 | ctx.ReadI8() | MqReadI8_RT | |
int16 | ctx.ReadI16() | MqReadI16_RT | |
int32 | ctx.ReadI32() | MqReadI32_RT | |
int64 | ctx.ReadI64() | MqReadI64_RT | |
string | ctx.ReadSTR() | MqReadSTR_RT | |
binary | ctx.ReadBIN() | MqReadBIN_RT | |
bool | ctx.ReadBOL() | MqReadBOL_RT | |
float | ctx.ReadFLT() | MqReadFLT_RT | |
double | ctx.ReadDBL() |
read a PRIMITIVE TYPE from the read-data-package …
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | val_out | the value to read |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
C-API: MqContextC_ReadApi_Block_C_API - MqContextC - read a block-of-data outof a read-data-package …
ctx.ReadL_END()
top finish to extract a list-items from the read-data-package. … → API: rb_mqmsgque_MqContextC_ReadL_END
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ReadL_START(?buf:MkBufferC=nil?)
top start to extract a list-items from the read-data-package. … → API: rb_mqmsgque_MqContextC_ReadL_START
Initialize the read with the current body-item or an optional MkBufferC. This command requires a final ctx.ReadL_END()
to finish the read.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | buf | an optional MkBufferC as result from a previous RMqReadBUF call or nil to use the next item from the read-data-package. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ReadT_END()
top finish to extract a longterm-transaction-item from the read-data-package. … → API: rb_mqmsgque_MqContextC_ReadT_END
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ReadT_START()
top start to extract a longterm-transaction-item from the read-data-package. … → API: rb_mqmsgque_MqContextC_ReadT_START
Initialize the read with the current-item or an optional MkBufferC. The current-item have to be the first item in the read-data-package. This command requires a final ctx.ReadL_END()
to finish the read.
Example from server.rb
→ read the results from a service-call with transaction-support
def TRN2 ReadT_START() @i = ReadI32() ReadT_END() @j = ReadI32() end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
C-API: MqContextC_ReadApi_Misc_C_API - MqContextC - various functions to work on a read-data-package …
MkTypeE ctx.ReadGetNextType()
top get the type (MkTypeE) of the next Item in the read-data-buffer or "0" if not available → API: rb_mqmsgque_MqContextC_ReadGetNextType
[in] | ctx | the MqContextS instance to work on |
int32 ctx.ReadGetNumItems()
top get the number of items left in the read-data-package … → API: rb_mqmsgque_MqContextC_ReadGetNumItems
[in] | ctx | the MqContextS instance to work on |
bool ctx.ReadItemExists()
top check if an item exists in the read-data-package … → API: rb_mqmsgque_MqContextC_ReadItemExists
[in] | ctx | the MqContextS instance to work on |
ctx.ReadUndo()
top undo the last MqContextC READ API function call … → API: rb_mqmsgque_MqContextC_ReadUndo
Put the internal position-pointer 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.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
RouteCreate | create/delete a routing-link between context an a service using route | ||
RouteDelete | delete a routing-link created with MqRouteCreate | ||
RouteGetPath | return the absolut route-connection-string up to the current ctx … | ||
RouteGetTree | create an overview about all available routing-target and services … | ||
RouteResolve | return a list of all context belonging to ident … | ||
RouteTraverse | traverse a tree down and call service if available. |
C-API: MqContextC_RouteApi_C_API - MqContextC - setup and manage a routing-link …
A routing-link is the connection of two context, the route-source and the route-target, with a unspecifiend number of hub-context in between using a specific service-token.
A single context is identified by the context-identifier as returned by MqClassIdentGet.
A routing-link can be created using Service-Level-Routing or Package-Level-Routing.
The difference between Service-Level-Routing and Package-Level-Routing is the public versa private behaviour.
Summary:
ctx.RouteCreate(route:string, service:string, ?overwrite:bool=false?)
using a route-connection-string and a service-token. The TCP/IP model define the following layers (from: https://www.geeksforgeeks.org/tcp-ip-model/) :
The libmqmsgque layer model is an extension to the TCP/IP layer model.
protocoll_mq.h
→ this is the "syntax" of the protocol. This layer provide the MqContextC-ServiceApi ontop of the Application Layer.
The master-slave-link is used to create a mesh of nodes defined by different parent-context. The master control the slave.
The master-slave-link is used to perform the following tasks:
In difference to the client-server-link the master-slave-link connect two independent parent-context in the same process or thread (e.g. node). This leads to the restriction that only the master-context can be a server-context because only one server-context per node is possible.
node-0 | node-1/2 | node-3/4/5 =================================================================== | <- client/server link -> | <- client/server link -> | | <-- master/slave link --> | |- client1-0 -|- server3 ... |- server1 -| | |- client1-1 -|- server4 ... client0-0 -| |- server2 -|- client1-2 -|- server5 ...
Definition of the "master-context"
Definition of the "slave-context"
0
.Definition of the "worker-context"
0
./etc/services
0
slave-id | value | definition |
---|---|---|
MQ_SLAVE_MAX | 1024 | internal: the maximum slave-id … . |
MQ_SLAVE_USER | 10 | internal: start of user-defined-slave-id . |
MQ_SLAVE_LOOPBACK | 0 | internal: the loopback-slave-id, (call my own services) . |
MQ_SLAVE_FILTER | 1 | internal: the filter-slave-id, (on a master get the filter-slave) . |
MQ_SLAVE_MASTER | 1 | internal: the master-slave-id, (on a slave get the master) . |
MQ_SLAVE_OTHER | 1 | internal: on the master-ctx get the slave-ctx and on the slave-ctx get the master-ctx . |
range | definition |
---|---|
0 <= slave-id < MQ_SLAVE_MAX | range of valid slave-id's |
0 <= slave-id < MQ_SLAVE_USER | internale usage |
MQ_SLAVE_USER <= slave-id < MQ_SLAVE_MAX | external usage |
Definition of the "LOOPBACK" (0) slave
client | server | =========================================== | <--- client/server ---> | <-- loop --> | | <------ master/slave -----> | client -- | -- server -- | -- client -- # == == # server -- | -- client -- #
slave-id = 0
. MyLoopServer.rb
→ create a new loop-server require "rbmqmsgque" include RbMsgque::MqMsgque # package-item class MyLoopServer < MqContextC attr_reader :mydata # factory startup def initialize() super() ConfigSetServerSetup(method(:ServerSetup)) # set the "mydata" attribute to the master-context @mydata = "Hello World" end # service to serve all EXTERNAL requests for token "HLWO" def HLWO_srv # get the "loopback" context loop = SlaveGet(MqSlaveE::LOOPBACK) # call the LOOP service on the SAME server loop.Send("W","LOOP") # answer HLWO with string-return from LOOP Send("R", "C", loop.ReadSTR()) end # service to serve all INTERNAL requests for token "LOOP" def LOOP_srv(loop) # get the "master" context master = loop.SlaveGetMaster() # answer LOOP with data from MASTER->mydata attribute loop.Send("R", "C", master.mydata) end # define a service as link between the token "HLWO" and the callback "HLWO_srv" def ServerSetup loop = SlaveGet(MqSlaveE::LOOPBACK) # EXTERNAL: link the "HLWO" service with "HLWO_srv" ServiceCreate("HLWO",method(:HLWO_srv)) # INTERNAL: link the "LOOP" service with "LOOP_srv" loop.ServiceCreate("LOOP",method(:LOOP_srv)) end end # ==================================================== # package-main # create the "MyLoopServer" factory… and the instance srv = MqFactoryC.Add(MyLoopServer).New() begin srv.LinkCreate(ARGV) srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex srv.ErrorCatch(ex) ensure srv.Exit() end
Performance analyse
Nhi1Exec perfclient.c --parent --wrk ? @ perfserver.c
Nhi1Exec -r=uds perfserver.c --spawn|fork|thread
Nhi1Exec -r=uds perfclient.c --parent --wrk ?
perfclient worker perfserver ========== ====== ========== | |- loop --wrk x |- MqSlaveWorker(...) -> worker[1] |- MqSend(worker[1],"E","STR0..") -> PerfWorker_I160(...) |- loop endless |- MqContextCreate(...) |- MqLinkCreate(...) <-> MqContextCreate(...) |- MqContextDelete(...) <-> MqContextDelete(...) |- sleep x sec |- loop --wrk x |- MqSend(worker[1],"C"..,"END0") -> PerfWorker_END0(...) | |- stop loop |- "callback" - add number to all <- |- return #context
setup | –wrk | # worker-context | performance | info |
---|---|---|---|---|
pipe | 1 | 2500 | 1000 | the pipe start a new worker-context with spawn |
spawn | 1 | 2500 | <1000 | same as pipe but use network-protocoll |
fork | 1 | 3800 | 4000 | the fork is faster than spawn |
thread | 1 | 16500 | 9000 | the thread is faster than fork |
pipe | 4 | 8000 | 4500 | the worker scale linear up to number of processors |
spawn | 4 | 7600 | <4500 | - |
fork | 4 | 23200 | 11500 | - |
thread | 4 | 55500 | 27500 | - |
pipe | 8 | 10000 | 5500 | the additional scaling up to the max hyper-threading does not really help |
spawn | 8 | 9100 | <5500 | - |
fork | 8 | 23200 | 11500 | - |
thread | 8 | 55500 | 27500 | - |
A client-server connection is defined with the route-connection-string as a composition of "identifier" and is build like a UNIX directory tree with the initial client as root.
Example: GUI/Data Frontend
With --ident-from prefix|factory the identifier is defined as prefix-identifier or factory-identifer.
A route-connection-string is the path between TWO locations in the tree using the UNIX syntax:
short | syntax | direction |
---|---|---|
dot | . | current-context |
double-dot | .. | previous-context |
slash | / | root-context (the client) |
"string" | xxx | next-context with name xxx |
path between "DB" and "header"
relative: ctx.RouteCreate("../GUI/header",service)
absolute: ctx.RouteCreate("/frontend/GUI/header",service)
path between "footer" and "DB"
relative: ctx.RouteCreate("../../DB",service)
absolute: ctx.RouteCreate("/frontend/DB",service)
path between "frontend" and "footer"
relative: ctx.RouteCreate("GUI/footer",service)
absolute: ctx.RouteCreate("/frontend/GUI/footer",service)
The LibMqMsgque-Service-Layer-Routing create proxy-services (MqServiceProxyRoundRobin ...) between frontend and footer. (example c++)
The MqRouteCreate will take the following action:
Attention:
overwrite=true
to guarantee that a route is available....
ctx.RouteCreate(route:string, service:string, ?overwrite:bool=false?)
top create/delete a routing-link between context an a service using route → API: rb_mqmsgque_MqContextC_RouteCreate
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | route | the absolute or relative path to the target-context, if NULL or '\0' the current context is returned. |
[in] | service | the service token on the target context |
[in] | overwrite | if overwrite=false an error is raised if the service already exists. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.RouteDelete(route:string, service:string, ?overwrite:bool=false?)
top delete a routing-link created with MqRouteCreate → API: rb_mqmsgque_MqContextC_RouteDelete
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | route | the absolute or relative path to the target-context, if NULL or '\0' the current context is returned. |
[in] | service | the service token on the target context |
[in] | overwrite | if overwrite=false an error is raised if the service already exists. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
string ctx.RouteGetPath()
top return the absolut route-connection-string up to the current ctx … → API: rb_mqmsgque_MqContextC_RouteGetPath
The absolut route-connection-string is the route starting at root (e.g. "/").
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | path_out | the return path or nil on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MkBufferListC ctx.RouteGetTree()
top create an overview about all available routing-target and services … → API: rb_mqmsgque_MqContextC_RouteGetTree
The data returned is a list of "ROUTE|IDENT|SERVICE,..."
string items.
ROUTE
is the route-connection-string used in ctx.RouteCreate(route:string, service:string, ?overwrite:bool=false?)
. IDENT
is the MqClassIdentGet and usually the final part of the route-connection-string. SERVICE
is the list of services available at IDENT
.Example from MyWorker.rb
→ get the "Tree" as service
void TREE () { Send("R", "L", RouteGetTree()); }
Example from tests/route2.test -> route2-1-0
/cl-0/sv-0/svWO2-11/svWO3-11|svWO3-11-0-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11/svWO3-11|svWO3-11-1-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11/svWO3-11|svWO3-11-2-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11/svWO3-12|svWO3-12-0-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11/svWO3-12|svWO3-12-1-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11/svWO3-12|svWO3-12-2-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11|svWO2-11-0-2|FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11|svWO2-11-1-2|FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11|svWO2-11-2-2|FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12/svWO3-11|svWO3-11-0-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12/svWO3-11|svWO3-11-1-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12/svWO3-11|svWO3-11-2-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12/svWO3-12|svWO3-12-0-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12/svWO3-12|svWO3-12-1-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12/svWO3-12|svWO3-12-2-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12|svWO2-12-0-2|FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12|svWO2-12-1-2|FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-12|svWO2-12-2-2|FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0|sv-0-0-2|FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0|sv-0-1-2|FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0|sv-0-2-2|FOID,HLWO,HLWS,PATH,TREE /cl-0|cl-0-0-2|HLWO,HLWS /cl-0|cl-0-1-2|HLWO,HLWS /cl-0|cl-0-2-2|HLWO,HLWS /cl-0/sv-0/svWO2-11/svWO3-11|svWO3-11-0-2|FINL,FOID,HLWO,HLWS,PATH,TREE /cl-0/sv-0/svWO2-11/svWO3-11|svWO3-11-1-2|FINL,FOID,HLWO,HLWS,PATH,TREE
The following information is available:
cl-0
cl-0
, are reachable: cl-0-
.... sv
... [in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | treeP_out | the tree-object with the results… |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
[MqContextC...] ctx.RouteResolve(ident:string, ?retnum:int32=-1?)
top return a list of all context belonging to ident … → API: rb_mqmsgque_MqContextC_RouteResolve
This api-proc is used to return all context with MqLinkS::targetIdent == ident
.
In addition the following special ident are recognized:
Example from server.rb
→ in a service call return all connected targets
RouteResolve(ReadSTR()).each do |myctx| SendSTR(myctx.LinkGetTargetIdent()) end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | ident | The identifer to search the context for |
[in] | retnum | The maximum number-of-items accepted in the result-array, if <0 than MQ_ROUTE_CTX_MAX is used. |
ctx.RouteTraverse(service:string, ?args:MkBufferListC...=nil?)
top traverse a tree down and call service if available. → API: rb_mqmsgque_MqContextC_RouteTraverse
The MqRouteTraverse is intended to call a service on all-routes "*"
starting from ctx.
This is a tool to be used to do maintenance work, sometimes a service is changed (e.g MqRouteCreate) or an internal status need to be reset.
The following internal tasks are performed ( C notation ) :
"*"
to get all routes starting from the ctx up to MQ_ROUTE_CTX_MAX routes : sRouteTool_CB
set the flag[i]
to 1
to signal done.[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | service | the service token to be called |
[in] | args | command-line-arguments passed as arguments to the service call |
SendTT | MqContextC - append a native PRIMITIVE TYPE value to the send-data-package … | ||
SendBFL | append a MkBufferListC object to the send-data-package object … | ||
SendBinaryR | append a MkBinaryR object to the send-data-package. … | ||
SendBUF | append a MkBufferC object to the send-data-package object … | ||
SendBUS_FLAT | append a MkBufferStreamC object to the send-data-package object … | ||
SendHDL | send the handle to the send-data-package | ||
SendL_FLAT | append a MkBufferListC object as flat list of items to the send-data-package object … | ||
SendLONG | send the long native object to the send-data-package | ||
SendStringR | MqContextC - append a native PRIMITIVE TYPE value to the send-data-package … |
SendEND | MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service … | ||
SendEND_AND_CALLBACK | finish the send-data-block, call the remote service, do not-wait for the result but expect the result on a callback … | ||
SendEND_AND_SUB | finish the send-data-block, call the remote service, do wait for the result and expect multiple sub-results on a callback … | ||
SendEND_AND_TRANSACTION | finish the send-data-block, call the remote service to do a longterm-transaction-call … | ||
SendEND_AND_WAIT | finish the send-data-block, call the remote service and wait for result… | ||
SendSTART | initialize the send-data-package. … | ||
SendSYNC | garantee that all pending asynchronous-service-calls are processed. … |
SendL_END | finish to append an embedded body-list-item to the send-data-package. … | ||
SendL_START | start to append an embedded body-list-item to the send-data-package. … | ||
SendT_END | closed a longterm-transaction-item … | ||
SendT_START | open a longterm-transaction-item … |
SendERROR | send the data from the MkErrorC to the link target . … | ||
SendRETURN | MqContextC - finish the send-data-block on the server and optional return the results. … | ||
SendRETURN_SUB | return Sub-Data-Blocks required by MqSendEND_AND_SUB … |
C-API: MqContextC_SendApi_C_API - MqContextC - construct an outgoing send-data-package …
A data-package is send in two different scenarios:
Sending data is an active task and the opposite of reading data, which is a passive task. Active means that the send process is triggered by the software workflow or by the user.
For each basic type defined in MkBufferC, there is a send function and some help functions.
If timeout != 0 is used, the application enters the event loop and waits in the current process or thread for timeout seconds until the service call is finished.
While waiting for a result, the application can continue to work on other events that are in the same or in a different process or thread.
Example-1: a service call, send and read a data-package
On a client: perform a service call
send the service-call | MqSendSTART → SendTT... → MqSendEND_AND_WAIT |
read the result package | ReadTT... → ... |
on a server: answer a service call
read the service-call | ReadTT... → ... |
send the result package | MqSendSTART → SendTT... → MqSendRETURN |
Important in the code from above is the last command MqSendEND_AND_WAIT because this is just one of five possibilities:
command | synchron | database | result |
---|---|---|---|
MqSendEND | no | no | no |
MqSendEND_AND_WAIT | yes | no | single return data |
MqSendEND_AND_SUB | yes | no | multiple return data |
MqSendEND_AND_CALLBACK | no | no | single return data |
MqSendEND_AND_TRANSACTION | no | yes | two return data |
To send a data-package is one task, to send it to the right receiver is an other one. The right receiver is identified using the token parameter argument. This parameter have to be a 4 character string. You'll probably ask "why 4?" the answer is that this string should be "human" readable and easy to "compare". As solution this string is mapped to a 4 byte integer used to find the proper key/value entry in the service-hash-table on the server. (in short: to search an integer is much faster as to search a string)
Example-2: (in C) At the client, calling the service and wait for an answer
... or using the MqContextC HIGH API
Example-3: (in C) At the server, answer the service call
... or using the MqContextC HIGH API
C-API: MqContextC_SendApi_Atom_C_API - MqContextC - append a native PRIMITIVE TYPE value to the send-data-package …
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the value to appending |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendBFL(val:MkBufferListC)
top append a MkBufferListC object to the send-data-package object … → API: rb_mqmsgque_MqContextC_SendBFL
The items of the list are send as list using MqSendL_START and MqSendL_END.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the pointer to an MkBufferListC object to send |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendBinaryR(val:binary)
top append a MkBinaryR object to the send-data-package. … → API: rb_mqmsgque_MqContextC_SendBinaryR
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the value to appending |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
[]) will be send. ctx.SendBUF(val:MkBufferC)
top append a MkBufferC object to the send-data-package object … → API: rb_mqmsgque_MqContextC_SendBUF
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the value to appending |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendBUS_FLAT(val:MkBufferStreamC)
top append a MkBufferStreamC object to the send-data-package object … → API: rb_mqmsgque_MqContextC_SendBUS_FLAT
The items of the stream are send flast as the stream is appended to the send-data-package.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the pointer to an MkBufferStreamC object to send |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendHDL(val:MK_HDL)
top send the handle to the send-data-package → API: rb_mqmsgque_MqContextC_SendHDL
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the handle-object to send |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendL_FLAT(val:MkBufferListC)
top append a MkBufferListC object as flat list of items to the send-data-package object … → API: rb_mqmsgque_MqContextC_SendL_FLAT
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the pointer to an MkBufferListC object to send |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendLONG(val:long)
top send the long native object to the send-data-package → API: rb_mqmsgque_MqContextC_SendLONG
on 64bit use a MqSendI64 and on 32bit use a MqSendI32
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the native long object to send |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendStringR(val:string)
top MqContextC - append a native PRIMITIVE TYPE value to the send-data-package … → API: rb_mqmsgque_MqContextC_SendStringR
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the value to appending |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
"MK_NULL"
will be send.ctx.SendTT(val:int8)
The SendTT provide a single function for every PRIMITIVE TYPE
attribute | return | command | C-API : |
---|---|---|---|
ctx.SendI8(val:int8) | MqSendI8_RT | ||
ctx.SendI16(val:int16) | MqSendI16_RT | ||
ctx.SendI32(val:int32) | MqSendI32_RT | ||
ctx.SendI64(val:int64) | MqSendI64_RT | ||
ctx.SendSTR(val:string) | MqSendSTR_RT | ||
ctx.SendBIN(val:binary) | MqSendBIN_RT | ||
ctx.SendBOL(val:bool) | MqSendBOL_RT | ||
ctx.SendFLT(val:float) | MqSendFLT_RT | ||
ctx.SendDBL(val:double) |
MqContextC - append a native PRIMITIVE TYPE value to the send-data-package …
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | val | the value to appending |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
C-API: MqContextC_SendApi_Basics_C_API - MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service …
calling a remote service and wait timeout seconds for an result. If timeout == 0
it is an asynchronous-service-call and if the timeout > 0
it is a synchronous-service-call.
service-call | blocking | timeout |
---|---|---|
synchronous | yes | timeout > 0 |
asynchronous | no | timeout == 0 |
blocking mean waiting max timeout seconds to finishing the service-call:
If an error was raised on the server during the service-processing… the following error-handling will be available
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=0 ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendEND(token:string[4], ?timeout:MkTimeoutE|int32=DEFAULT?)
top MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service … → API: rb_mqmsgque_MqContextC_SendEND
calling a remote service and wait timeout seconds for an result. If timeout == 0
it is an asynchronous-service-call and if the timeout > 0
it is a synchronous-service-call.
service-call | blocking | timeout |
---|---|---|
synchronous | yes | timeout > 0 |
asynchronous | no | timeout == 0 |
blocking mean waiting max timeout seconds to finishing the service-call:
If an error was raised on the server during the service-processing… the following error-handling will be available
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=0 ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendEND_AND_CALLBACK(token:string[4], callback:callable, ?timeout:MkTimeoutE|int32=DEFAULT?)
top finish the send-data-block, call the remote service, do not-wait for the result but expect the result on a callback … → API: rb_mqmsgque_MqContextC_SendEND_AND_CALLBACK
This function will never block and return immediately. Usually multiple MqSendEND_AND_CALLBACK are send and finally multiple MqProcessEvent are called to wait for the results.
Example from route_mq.c
→ (C) call a service using a callback
Be aware of the followig limitatitions if multiple MqSendEND_AND_CALLBACK are called with different ctx:
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | fCall | the function to process the service-call results |
[in] | callback | a user defined additional data-argument for the callback function (C-API only) |
[in] | fFree | the function to free the data-argument after use (C-API only) |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT= 0) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqSendEND_AND_CALLBACK
: callback signature ctx.SendEND_AND_SUB(token:string[4], callback:callable, ?timeout:MkTimeoutE|int32=DEFAULT?)
top finish the send-data-block, call the remote service, do wait for the result and expect multiple sub-results on a callback … → API: rb_mqmsgque_MqContextC_SendEND_AND_SUB
The goal of this service-call is, to split a big data-block into multiple pieces. A typical solution would be a database-application doing a select and sending EVERY row as a ctx.SendRETURN_SUB()
. At the end ONE final and EMPTY ctx.SendRETURN()
is used to delete the open transaction and finish the service call.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | fCall | the function to process the service-call results |
[in] | callback | a user defined additional data-argument for the callback function (C-API only) |
[in] | fFree | the function to free the data-argument after use (C-API only) |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=MK_TIMEOUT_USER ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendRETURN()
) is only called if the packet contains a data-item or on an error. If the packet is empty, only the transaction is closed.MqSendEND_AND_SUB
: callback signature ctx.SendEND_AND_TRANSACTION(token:string[4], callback:string[4], ?timeout:MkTimeoutE|int32=DEFAULT?)
top finish the send-data-block, call the remote service to do a longterm-transaction-call … → API: rb_mqmsgque_MqContextC_SendEND_AND_TRANSACTION
A longterm-transaction is a service-call with guaranteed delivery. guaranteed mean that the transaction is using the MqContextC STORAGE API to keep every step persistent being able to recover a step if something unexpected happen.
To link the result with the calling-environment a private transaction-item is used to save the calling-environment to the local-storage. If the local-storage is persistent, the calling-environment will even survive an application restart.
If the result from the public service-call arrives, the transaction-item will be extracted from the result and the private calling-environment will be initialized from the local-storage.
To create a persistent-transaction the MqContextC STORAGE API have to be setup as persistent. By default, an in-memory MqContextC STORAGE API is used.
The longterm-transaction-call has TWO results…
In difference to MqSendEND_AND_WAIT and MqSendEND_AND_CALLBACK a longterm-transaction-call have to survive an application restart. To achieve this goal… two features have to be available to process the results:
The transaction-item is the entry-id from the local internal database and is the public handle of the private data. If the transaction-item-private-data should be persistent (survive an application restart) the internal database have to be persistent using the Storage option.
The transaction-item-private-data requires a MqSendT_START … MqSendT_END at the beginning of the send-data-package.
The list of data-items in the transaction-item-private-data have to be provided by the programmer and is used to initialise the environment in the callback (for example an external database-entry-id).
In the transaction-callback the transaction-item-private-data have to be extracted with MqReadT_START … MqReadT_END at the beginning of the read-data-package.
The transaction-callback have to be a MqContextC_ServiceApi_Identifer defined with MqServiceCreate in the application setup code (like IServerSetup) and have to be available after an application restart.
If an error is raised on the server during the database-insert the function will return this error immediately. During waiting for the return the event-loop is used to process other events. Use IEvent to add your tasks into the event loop.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | callback | the MqContextC_ServiceApi_Identifer of the MqContextC_ServiceApi_Callback |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=MK_TIMEOUT_USER ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
Example from MyTransaction.rb
→ make a logterm-transaction-call using the LOW and the HIGH api
require "rbmqmsgque" include RbMsgque::MkKernel include RbMsgque::MqMsgque def callback(ctx) ctx.ReadT_START() myPrivateHandle = ctx.ReadSTR() ctx.ReadT_END() myServiceResult = ctx.ReadI32() STDOUT.puts "myPrivateHandle=#{myPrivateHandle}, myServiceResult=#{myServiceResult}" end # setup the client-context ctx = MqContextC.new begin ctx.ConfigSetName("MyTransaction") # setup commandline arguments used for parsing args = MkBufferListC.CreateLA(ARGV) # check if the '--token' option is available, default "SRVC" token = args.CheckOptionSTR("--token", "SRVC") # connect to the server ctx.LinkCreate(args) # register callback ctx.ServiceCreate("CLB1", method(:callback)) # send block using the LOW-Api ctx.SendSTART() ctx.SendT_START() ctx.SendSTR("Privat_Data_1") ctx.SendT_END() ctx.SendI32(11111) ctx.SendEND_AND_TRANSACTION(token, "CLB1") # send block using the HIGN-Api -> same as above, but shorter ctx.Send("T", "CLB1", "#{token}:(C)I", "Privat_Data_2", 22222) # now we wait for exact ONE result of the "ctx" ctx.ProcessEvent(MqWaitOnEventE::OWN) rescue Exception => ex ctx.ErrorCatch(ex) ensure ctx.Exit() end
ctx.SendEND_AND_WAIT(token:string[4], ?timeout:MkTimeoutE|int32=DEFAULT?)
top finish the send-data-block, call the remote service and wait for result… → API: rb_mqmsgque_MqContextC_SendEND_AND_WAIT
If an error is raised on the server during the service-processing the function will return this error immediately. During waiting for the return the event-loop is used to process other events. Use IEvent to add your tasks into the event loop.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (MK_TIMEOUT_DEFAULT=MK_TIMEOUT_USER ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendSTART()
top initialize the send-data-package. … → API: rb_mqmsgque_MqContextC_SendSTART
This function must be the first statement in a send-data-block.
If the socket is closed or failed, the connection is established with a MqLinkConnect.
Note that during MqLinkConnect the event-loop is called and your read-data-package may be invalid.
It is recommended to perform all READ operations first and then all SEND operations.
From MqSendSTART to MqSendEND is a send-data-block and no event-loop action is allowed between them.
The event-loop could modify the already started send-data-package and corrupt the data.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendSYNC()
top garantee that all pending asynchronous-service-calls are processed. … → API: rb_mqmsgque_MqContextC_SendSYNC
The asynchronous-service-call is defined at: MqContextC_ServiceApi_C_API.
All service-calls to a specific ctx are queued in a service-call-pipeleine. The synchronous-service-call is blocking the service-call-pipeleine until the synchronous-service-call is finished. The asynchronous-service-call does NOT blocking the pipeline and so all asynchronous-service-call are processed in parallel. The MqSendSYNC is used if multiple asynchronous-service-calls are done to a single ctx and this ctx should be blocked until all asynchronous-service-calls are finished. The MqSendSYNC is just an normal blocking synchronous-service-call which is only finished after all asynchronous-service-calls are finished.
Example from perfclient.c
→ sending a bulk of asynchronous-sevice-requests
The last MqSendSYNC garantee the all previous asynchronous-service-calls are finished.
C-API: MqContextC_SendApi_Block_C_API - MqContextC - a wrapper to send a list-block or a transaction-block …
start to append an embedded body-list-item to the send-data-package. …
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendL_END()
top finish to append an embedded body-list-item to the send-data-package. … → API: rb_mqmsgque_MqContextC_SendL_END
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendL_START()
top start to append an embedded body-list-item to the send-data-package. … → API: rb_mqmsgque_MqContextC_SendL_START
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendT_END()
top closed a longterm-transaction-item … → API: rb_mqmsgque_MqContextC_SendT_END
finish a setup-block started with MqSendT_START. read more at MqSendEND_AND_TRANSACTION.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendT_START()
top open a longterm-transaction-item … → API: rb_mqmsgque_MqContextC_SendT_START
Every longterm-transaction-item have to be closed with MqSendT_END. Between MqSendT_START and MqSendT_END, a non specified number of other items can be added. These items are saved in a local database (in-memory or file-based) and the rowid is send as transaction-id to the link-target. By Default only the in-memory-database is used. To switch to a file-based database use the MqStorageOpen function.
Example from server.rb
→ make a service-call with transaction-support
def TRNS SendSTART() SendT_START() SendI32(9876) SendT_END() SendI32( ReadI32() ) SendEND_AND_TRANSACTION("ECOI", "TRN2") ProcessEvent(MqWaitOnEventE::ONCE) SendSTART() SendI32(@i) SendI32(@j) SendRETURN() end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
C-API: MqContextC_SendApi_Return_C_API - MqContextC - finish the send-data-block on the server and optional return the results. …
Every service-handler have to use this function at the end to return the results or the error. If an error is returned the local MkErrorC is reset. The following behaviour is used:
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendERROR()
top send the data from the MkErrorC to the link target . … → API: rb_mqmsgque_MqContextC_SendERROR
If an error is available the error-number and the error-text is send to the link target. After send the error is reset. This function only raise an error if the sending self fails or the MkErrorDEFAULT is set and the ctx is a client-context.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendRETURN()
top MqContextC - finish the send-data-block on the server and optional return the results. … → API: rb_mqmsgque_MqContextC_SendRETURN
Every service-handler have to use this function at the end to return the results or the error. If an error is returned the local MkErrorC is reset. The following behaviour is used:
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendRETURN_SUB()
top return Sub-Data-Blocks required by MqSendEND_AND_SUB … → API: rb_mqmsgque_MqContextC_SendRETURN_SUB
Every service-handler CAN use this function at the end of a data block if the caller used MqSendEND_AND_SUB to initiate the service call. MqSendEND_AND_SUB will block until ithe final ctx.SendRETURN()
was send.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ServiceCreate | create a link between a service-token and a service-callback … | ||
ServiceDelete | delete a service. … | ||
ServiceIsTransaction | check if the ongoing-service-call belongs to a transaction … | ||
ServiceProxy | create a service to link a master-context with a slave-context. … | ||
ServiceProxyCtx | same as MqServiceProxy but use an MqContextC as input. | ||
ServiceProxyCtxExists | check if service who belongs to token is a proxy-service | ||
ServiceProxyRoundRobin | create a proxy-service using Round-Robin as load-balancer … | ||
ServiceStorage | setup a service listen on a MqContextC_ServiceApi_Identifer and save all read-data-package into the STORAGE … | ||
ServiceTokenCheck | in an ongoing-service-call check if the current MqContextC_ServiceApi_Identifer is token … | ||
ServiceTokenExists | check if the MqContextC_ServiceApi_Identifer token is defined as ctx service … | ||
ServiceTokenGet | in an ongoing-service-call get the current MqContextC_ServiceApi_Identifer … |
C-API: MqContextC_ServiceApi_C_API - MqContextC - create and manage a service …
To provide a service is the main purpose of a server and the main-purpose of a client/server connection is to call a service and to process the result.
A service can be defined on the server or on the client. On the server a service can be initial setup with IServerSetup method and finally cleanup with IServerCleanup.
A service is created with the MqServiceCreate and deleted with the MqServiceDelete.
A service can be created and deleted during the entire life-cycle of the server or the client. If the server/client-context is deleted all services of the are deleted also.
A MqServiceDelete is not required.
Creating or deleting a service is like granting or revoking the right to access a single feature.
eventloop
callback
Example from MyServer.rb
→ define the service SRV1 on the server-link-setup
require "rbmqmsgque" include RbMsgque::MqMsgque # package-item class MyServer < MqContextC # factory startup def initialize() super ConfigSetServerSetup(method(:ServerSetup)) end # define a service as link between the token "HLWO" and the callback "MyFirstService" def ServerSetup ServiceCreate("HLWO",method(:MyFirstService)) end # service to serve all incoming requests for token "HLWO" def MyFirstService() SendSTART() SendSTR(ReadSTR() + " World") SendRETURN() end end # ==================================================== # package-main # create the "MyServer" factory… and object srv = MqFactoryC.Add(MyServer).New() begin srv.LinkCreate(ARGV) srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex srv.ErrorCatch(ex) ensure srv.Exit() end
ctx.ServiceCreate(token:string[4], callback:callable)
top create a link between a service-token and a service-callback … → API: rb_mqmsgque_MqContextC_ServiceCreate
The servive-token (e.g. MqContextC_ServiceApi_Identifer) have to be unique but the service-callback (e.g. MqServiceCallbackF) not. If a service-callback is not unique than this is called an alias, use string[4] ctx.ServiceTokenGet()
to get the current token for an incoming-service-call.
The service-callback have to be callable by the server and/or by the child and/or the slave context. A static-callback is a good choice to achive this goal.
The filter, a slave-context, is setup with the initial factory using the initial-class (MqContextC) usually different from the server-class (MyServer…). The filter need the service-callback, usually shared with the server, to report a filter-message to the server.
To distinguish the server and the filter the following functions are used
(all function cann be called as either server or filter context):
ctx.SlaveGet(MASTER)
for the server ctx.SlaveGet(FILTER)
for the filter "if"
clause and the server check"if"
clause and the slave check
Example from Filter6.rb
→ setup the services for server and filter
def ServerSetup ftr = SlaveGetFilter() ServiceCreate( "LOGF", method(:LOGF)) ServiceCreate( "EXIT", method(:EXIT)) ServiceCreate( "SOEX", method(:SOEX)) ServiceCreate( "+ALL", method(:FilterIn)) ServiceStorage( "PRNT") ServiceStorage( "PRN2") ftr.ServiceCreate( "WRIT", method(:WRIT)) ServiceCreate( "WRIT", method(:WRIT)) ftr.ServiceProxy( "WRT2", MqSlaveE::MASTER) end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | fCall | the C-function to process the incoming service-request (C-API only) |
[in] | callback | the user defined callback as data-argument for the C-function fCall |
[in] | fFree | the function to free the data-argument after use (C-API only) |
[in] | fMark | the function to mark the data-argument during garbage-collection (C-API only) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqServiceCreate
: callback signature ctx.ServiceDelete(token:string[4])
top delete a service. … → API: rb_mqmsgque_MqContextC_ServiceDelete
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
bool ctx.ServiceIsTransaction()
top check if the ongoing-service-call belongs to a transaction … → API: rb_mqmsgque_MqContextC_ServiceIsTransaction
A service-call can be with-transaction (return true if the package was send with MqSendEND_AND_WAIT or MqSendEND_AND_CALLBACK) or can be without-transaction (return false if the package was send with MqSendEND)
[in] | ctx | the MqContextS instance to work on |
ctx.ServiceProxy(token:string[4], ?id:MqSlaveE|int32=MQ_SLAVE_OTHER?)
top create a service to link a master-context with a slave-context. … → API: rb_mqmsgque_MqContextC_ServiceProxy
This function is used to create a proxy-service to forward the body-data from the read-data-package of the master to the send-data-package of the slave. The data is not changed. This function support the reverse-operation also. If the ctx is a master-context than the data is send to slave identified by id. If the ctx is a slave-context than the data is send to the master of the slave.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | id | the SlaveId to unique identify the master/slave link, the id < MQ_SLAVE_USER is internal. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ServiceProxyCtx(token:string[4], target:MqContextC)
top same as MqServiceProxy but use an MqContextC as input. → API: rb_mqmsgque_MqContextC_ServiceProxyCtx
bool ctx.ServiceProxyCtxExists(token:string[4], target:MqContextC)
top check if service who belongs to token is a proxy-service → API: rb_mqmsgque_MqContextC_ServiceProxyCtxExists
This is used for route (MqRouteDelete) to identify the service-usage
ctx.ServiceProxyRoundRobin(token:string[4], ident:string)
top create a proxy-service using Round-Robin as load-balancer … → API: rb_mqmsgque_MqContextC_ServiceProxyRoundRobin
This function is used to create a proxy-service to forward the body-data from the read-data-package of the master-context to the send-data-package of the slave-context. The data is not changed. This function support the reverse-operation also. If the ctx is a master-context than the data is send to one of the slave-context identified by ident. If the ctx is a slave-context than the data is send to the master-context of the slave.
The Round-Robin-Load-Balancer is only used for the direction from the master-context to the slave-context if the name-resolution return multiple target-context for the single ident.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
[in] | ident | the targetIdent used to select a list slave-Context for the Round-Robin |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.ServiceStorage(token:string[4])
top setup a service listen on a MqContextC_ServiceApi_Identifer and save all read-data-package into the STORAGE … → API: rb_mqmsgque_MqContextC_ServiceStorage
In a shortterm-transaction-synchronous-service-call the service will return an empty data package. In a longterm-transaction-synchronous-service-call the data will return as normal.
Example from Filter6.rb
→ using MqServiceStorage to store all packages from service PRNT
and PRN2
into database
def ServerSetup ftr = SlaveGetFilter() ServiceCreate( "LOGF", method(:LOGF)) ServiceCreate( "EXIT", method(:EXIT)) ServiceCreate( "SOEX", method(:SOEX)) ServiceCreate( "+ALL", method(:FilterIn)) ServiceStorage( "PRNT") ServiceStorage( "PRN2") ftr.ServiceCreate( "WRIT", method(:WRIT)) ServiceCreate( "WRIT", method(:WRIT)) ftr.ServiceProxy( "WRT2", MqSlaveE::MASTER) end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
bool ctx.ServiceTokenCheck(token:string[4])
top in an ongoing-service-call check if the current MqContextC_ServiceApi_Identifer is token … → API: rb_mqmsgque_MqContextC_ServiceTokenCheck
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
bool ctx.ServiceTokenExists(token:string[4])
top check if the MqContextC_ServiceApi_Identifer token is defined as ctx service … → API: rb_mqmsgque_MqContextC_ServiceTokenExists
This code is used to detect if a service with identifer token exists.
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
string[4] ctx.ServiceTokenGet()
top in an ongoing-service-call get the current MqContextC_ServiceApi_Identifer … → API: rb_mqmsgque_MqContextC_ServiceTokenGet
This function is needed on the server to process a service-request defined as +ALL
or as an alias to extract the current MqContextC_ServiceApi_Identifer.
[in] | ctx | the MqContextS instance to work on |
SlaveCheck | check if slave-id is valid | ||
SlaveCreate | create a master/slave link between the master-parent-context and the slave-parent-context … | ||
SlaveDelete | Delete a slave object from a master/slave link identified by id. … | ||
SlaveGet | get the slave-context from a master-context … | ||
SlaveGetFilter | get the filter-ctx or the master-ctx … | ||
SlaveGetMaster | opposite function of MqSlaveGetFilter | ||
SlaveGetProxy | on slave return the master and on master return the slave identified by id. | ||
SlaveIs | is the context a slave-context ? … | ||
SlaveWorker | create a master/slave link using the image of the ctx object self. … |
C-API: MqContextC_SlaveApi_C_API - MqContextC - create and manage a slave context …
The master-slave-link is used to create a mesh of nodes defined by different parent-context. The master control the slave.
The master-slave-link is used to perform the following tasks:
In difference to the client-server-link the master-slave-link connect two independent parent-context in the same process or thread (e.g. node). This leads to the restriction that only the master-context can be a server-context because only one server-context per node is possible.
node-0 | node-1/2 | node-3/4/5 =================================================================== | <- client/server link -> | <- client/server link -> | | <-- master/slave link --> | |- client1-0 -|- server3 ... |- server1 -| | |- client1-1 -|- server4 ... client0-0 -| |- server2 -|- client1-2 -|- server5 ...
Definition of the "master-context"
Definition of the "slave-context"
0
.Definition of the "worker-context"
0
./etc/services
0
slave-id | value | definition |
---|---|---|
MQ_SLAVE_MAX | 1024 | internal: the maximum slave-id … . |
MQ_SLAVE_USER | 10 | internal: start of user-defined-slave-id . |
MQ_SLAVE_LOOPBACK | 0 | internal: the loopback-slave-id, (call my own services) . |
MQ_SLAVE_FILTER | 1 | internal: the filter-slave-id, (on a master get the filter-slave) . |
MQ_SLAVE_MASTER | 1 | internal: the master-slave-id, (on a slave get the master) . |
MQ_SLAVE_OTHER | 1 | internal: on the master-ctx get the slave-ctx and on the slave-ctx get the master-ctx . |
range | definition |
---|---|
0 <= slave-id < MQ_SLAVE_MAX | range of valid slave-id's |
0 <= slave-id < MQ_SLAVE_USER | internale usage |
MQ_SLAVE_USER <= slave-id < MQ_SLAVE_MAX | external usage |
Definition of the "LOOPBACK" (0) slave
client | server | =========================================== | <--- client/server ---> | <-- loop --> | | <------ master/slave -----> | client -- | -- server -- | -- client -- # == == # server -- | -- client -- #
slave-id = 0
. MyLoopServer.rb
→ create a new loop-server require "rbmqmsgque" include RbMsgque::MqMsgque # package-item class MyLoopServer < MqContextC attr_reader :mydata # factory startup def initialize() super() ConfigSetServerSetup(method(:ServerSetup)) # set the "mydata" attribute to the master-context @mydata = "Hello World" end # service to serve all EXTERNAL requests for token "HLWO" def HLWO_srv # get the "loopback" context loop = SlaveGet(MqSlaveE::LOOPBACK) # call the LOOP service on the SAME server loop.Send("W","LOOP") # answer HLWO with string-return from LOOP Send("R", "C", loop.ReadSTR()) end # service to serve all INTERNAL requests for token "LOOP" def LOOP_srv(loop) # get the "master" context master = loop.SlaveGetMaster() # answer LOOP with data from MASTER->mydata attribute loop.Send("R", "C", master.mydata) end # define a service as link between the token "HLWO" and the callback "HLWO_srv" def ServerSetup loop = SlaveGet(MqSlaveE::LOOPBACK) # EXTERNAL: link the "HLWO" service with "HLWO_srv" ServiceCreate("HLWO",method(:HLWO_srv)) # INTERNAL: link the "LOOP" service with "LOOP_srv" loop.ServiceCreate("LOOP",method(:LOOP_srv)) end end # ==================================================== # package-main # create the "MyLoopServer" factory… and the instance srv = MqFactoryC.Add(MyLoopServer).New() begin srv.LinkCreate(ARGV) srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex srv.ErrorCatch(ex) ensure srv.Exit() end
Performance analyse
Nhi1Exec perfclient.c --parent --wrk ? @ perfserver.c
Nhi1Exec -r=uds perfserver.c --spawn|fork|thread
Nhi1Exec -r=uds perfclient.c --parent --wrk ?
perfclient worker perfserver ========== ====== ========== | |- loop --wrk x |- MqSlaveWorker(...) -> worker[1] |- MqSend(worker[1],"E","STR0..") -> PerfWorker_I160(...) |- loop endless |- MqContextCreate(...) |- MqLinkCreate(...) <-> MqContextCreate(...) |- MqContextDelete(...) <-> MqContextDelete(...) |- sleep x sec |- loop --wrk x |- MqSend(worker[1],"C"..,"END0") -> PerfWorker_END0(...) | |- stop loop |- "callback" - add number to all <- |- return #context
setup | –wrk | # worker-context | performance | info |
---|---|---|---|---|
pipe | 1 | 2500 | 1000 | the pipe start a new worker-context with spawn |
spawn | 1 | 2500 | <1000 | same as pipe but use network-protocoll |
fork | 1 | 3800 | 4000 | the fork is faster than spawn |
thread | 1 | 16500 | 9000 | the thread is faster than fork |
pipe | 4 | 8000 | 4500 | the worker scale linear up to number of processors |
spawn | 4 | 7600 | <4500 | - |
fork | 4 | 23200 | 11500 | - |
thread | 4 | 55500 | 27500 | - |
pipe | 8 | 10000 | 5500 | the additional scaling up to the max hyper-threading does not really help |
spawn | 8 | 9100 | <5500 | - |
fork | 8 | 23200 | 11500 | - |
thread | 8 | 55500 | 27500 | - |
bool ctx.SlaveCheck(id:MqSlaveE|int32)
top check if slave-id is valid → API: rb_mqmsgque_MqContextC_SlaveCheck
[in] | ctx | the master-context as PARENT or CHILD |
[in] | id | the SlaveId to unique identify the master/slave link, the id < MQ_SLAVE_USER is internal. |
true
= valid or false
= invalid ctx.SlaveCreate(id:MqSlaveE|int32, slave:MqContextC)
top create a master/slave link between the master-parent-context and the slave-parent-context … → API: rb_mqmsgque_MqContextC_SlaveCreate
The slave-context have to be a sub-class of MqContextC and is owned by the master-context. Owned mean that no other external references should be used.
The slave-context will be deleted if the master-context is deleted and the slave-context will create a child-context if the master-context create a child context.
Example from server.cs
→ with reflection support... only the class is required :
Example from server.cc
→ without reflection support... the factory is required :
and the factory is used to create the object :
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the master context object as PARENT without a CHILD |
[in] | id | the SlaveId to unique identify the master/slave link, the id < MQ_SLAVE_USER is internal. |
[in] | slave | the slave context object as CLIENT-PARENT without a CHILD |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SlaveDelete(id:MqSlaveE|int32)
top Delete a slave object from a master/slave link identified by id. … → API: rb_mqmsgque_MqContextC_SlaveDelete
By default the slave-context object will be deleted if the master-context is deleted. Use this function to delete the parent-slave-context explicit and brake the master/slave link. If id is invalid nothing will happen. It is an error to delete a child-slave-context.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the master context object as PARENT without a CHILD |
[in] | id | the SlaveId to unique identify the master/slave link, the id < MQ_SLAVE_USER is internal. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqContextC ctx.SlaveGet(id:MqSlaveE|int32)
top get the slave-context from a master-context … → API: rb_mqmsgque_MqContextC_SlaveGet
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the master-context as PARENT or CHILD |
[in] | id | the SlaveId to unique identify the master/slave link, the id < MQ_SLAVE_USER is internal. |
[out] | ctx_out | the slave-context or nil on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqContextC ctx.SlaveGetFilter()
top get the filter-ctx or the master-ctx … → API: rb_mqmsgque_MqContextC_SlaveGetFilter
The functions MqSlaveGetFilter, MqSlaveGetMaster and MqSlaveGetProxy have the same purpose. A filter-pipeline has two ctx, one on the left and one on the right. The left-ctx is linked with the master-ctx and the right-ctx is linked to the slave-ctx. This function return the ctx wanted or an error if NOT available. The search is done using the following order:
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | ctx_out | the ctx or nil on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqContextC ctx.SlaveGetMaster()
top opposite function of MqSlaveGetFilter → API: rb_mqmsgque_MqContextC_SlaveGetMaster
MqContextC ctx.SlaveGetProxy(id:MqSlaveE|int32)
top on slave return the master and on master return the slave identified by id. → API: rb_mqmsgque_MqContextC_SlaveGetProxy
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the master or slave-context as PARENT or CHILD |
[in] | id | the SlaveId to unique identify the master/slave link, the id < MQ_SLAVE_USER is internal. |
[out] | ctx_out | the other-context or nil on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
bool ctx.SlaveIs()
top is the context a slave-context ? … → API: rb_mqmsgque_MqContextC_SlaveIs
[in] | ctx | the MqContextS instance to work on |
ctx.SlaveWorker(id:MqSlaveE|int32, ?fct:string="WORKER"?, ?args:MkBufferListC...=nil?)
top create a master/slave link using the image of the ctx object self. … → API: rb_mqmsgque_MqContextC_SlaveWorker
The slave-context is started as an independent process or thread based on the StartAs argument.
The start of a "worker" can be done at:
Example from server.rb
→ create a worker in a service-callback reading arguments from the service
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the master context object as PARENT without a CHILD |
[in] | id | the SlaveId to unique identify the master/slave link, the id < MQ_SLAVE_USER is internal. |
[in] | fct | the MqFactoryS::originalIdent or nil or '\0' or "WORKER" . if ident is nil or '\0' or WORKER the factory of ctx will be used if ident is MqFactoryS::originalIdent the factory defined will be used |
[in] | args | command-line arguments passed to the worker-client or the worker-server. all arguments prior the first @ token are added to the worker-client and the other arguments to the worker-server. example: --debug 5 --name hello @ --name myserver |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
StorageClose | close the storage. … | ||
StorageCount | count the number of storage-rows … | ||
StorageDecrRef | decrease the internal refCount lock of the database-entry | ||
StorageDelete | delete the storage-row identified by the transLIdP_inout … | ||
StorageErrCnt | increment and return the database row-error-count for the row defined with transLId | ||
StorageExport | export the read-data-package into the STORAGE … | ||
StorageImport | import the storage-package into the read-data-package … | ||
StorageIncrRef | increase the internal refCount lock of the database-entry | ||
StorageLog | log the storage the status of the open transactions | ||
StorageOpen | switch to a file-based-transaction-database … | ||
StorageResolve | extract the |
C-API: MqContextC_StorageApi_C_API - MqContextC - setup and manage a storage used to persist data-packages …
The storage is divided into: INTERNAL and EXTERNAL storage. Only the read-data-package can be stored or dumped into the storage.
The read-data-package is saved into the storage using:
ServiceStorage | setup a service listen on a MqContextC_ServiceApi_Identifer and save all read-data-package into the STORAGE … |
StorageExport | export the read-data-package into the STORAGE … |
The read-data-package is restored from the storage using:
StorageImport | import the storage-package into the read-data-package … |
ProxyForward | send the entire read-data-package-data to the link-target … |
All this usually happen in an Event Handler |
Some important facts of the storage-feature:
The following internal storages are supported:
Performance analyse:
Nhi1Exec perfclient.c --all --storage VALUE @ perfserver.c
.database | performance | host crash | application crash | info |
---|---|---|---|---|
memdb | 30.000 | data lost | data lost | non persistent |
tempdb | < 30.000 | data lost | data lost | uses memory and/or temporary file |
filedb (mem) | 10.000 | data lost | data safe | in memory filesystem |
filedb (disc) | 50 | data safe | data safe | disc-speed is the key factor |
ctx.StorageClose()
top close the storage. … → API: rb_mqmsgque_MqContextC_StorageClose
the next storage request will open the storage again with the location from Storage
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
int32 ctx.StorageCount()
top count the number of storage-rows … → API: rb_mqmsgque_MqContextC_StorageCount
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | cnt_out | number of rows, OLL if nothing is available |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.StorageDecrRef(transLId:int32)
top decrease the internal refCount lock of the database-entry → API: rb_mqmsgque_MqContextC_StorageDecrRef
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | transLId | storage-id … return from MqStorageImport |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
int32 ctx.StorageDelete(?*transLIdP_inout:int32=0?)
top delete the storage-row identified by the transLIdP_inout … → API: rb_mqmsgque_MqContextC_StorageDelete
The transLIdP_inout is the value returned by a previous MqStorageImport. If transLIdP_inout is nil than OLL
is used. MqStorageImport and MqStorageDelete work together link an transaction and every successfull transcation have to delete the transLIdP_inout out of the storage. After sucessfull delete the transLIdP_inout is set to 0LL
, on error the initial value is unchanged.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in,out] | transLIdP_inout | pointer to storage-id to delete, will be 0LL on success |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
int32 ctx.StorageErrCnt(transLId:int32)
top increment and return the database row-error-count for the row defined with transLId → API: rb_mqmsgque_MqContextC_StorageErrCnt
The storage is typical used in the following workflow:
<----- AT CALLING CLIENT ----->|<----- AT RECEIVING SERVER -----> | *setup transaction | make service-request --> *start service-handler | save request into storage wait for confirmation <-- confirm data receiving | *stop service-handler ==================== enter event loop ===================== | *start event-handler | load reqest from storage | process data *start transaction <-- send result-data process result-data | *stop event-handler *stop transaction |
Example Filter6 - store incoming packages into storage
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | transLId | storage-id … return from MqStorageImport |
[out] | cnt_out | the new value or -1 on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
int32 ctx.StorageExport()
top export the read-data-package into the STORAGE … → API: rb_mqmsgque_MqContextC_StorageExport
The export include all data required to setup a read-data-package later again. After import with MqStorageImport the read-data-package and the environment will be set as it was on MqStorageExport
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | ltid_out | if ltid_out != NULL return the storage-id |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
int32 ctx.StorageImport(?*transLIdP_inout:int32=0?)
top import the storage-package into the read-data-package … → API: rb_mqmsgque_MqContextC_StorageImport
Select the read-data-package from the database using the transLIdP. Only a package with refCount = 0
will be selected.
After selection the refCount is incremented and the next call to MqStorageImport using the same transLId will fail.
MqStorageImport is used together with MqStorageDelete or MqStorageDecrRef to delete the selected package from database or to undo the select.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) | ||||||||||
[in] | ctx | the MqContextS instance to work on | ||||||||||
[in,out] | transLIdP_inout | storage-id or nil or 0 … return from MqStorageExport
|
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
refCount=0
) with the smallest transLId
is read.refCount
is not reset or the package is not deleted, then the package remains locked and a subsequent call to MqStorageImport will read the next free package. ctx.StorageIncrRef(transLId:int32)
top increase the internal refCount lock of the database-entry → API: rb_mqmsgque_MqContextC_StorageIncrRef
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | transLId | storage-id … return from MqStorageImport |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.StorageLog(?callfunc:string="MK_NULL"?)
top log the storage the status of the open transactions → API: rb_mqmsgque_MqContextC_StorageLog
ctx.StorageOpen(storageFile:string)
top switch to a file-based-transaction-database … → API: rb_mqmsgque_MqContextC_StorageOpen
the value can also be set using the --storage
commandline option.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[in] | storageFile | the file used to create the transaction-database. Allowed values are:
|
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
{otherCtxP:MqContextC otherLIdP:int32} ctx.StorageResolve()
top extract the context->link.protect.rmtTransLId
entry from the database → API: rb_mqmsgque_MqContextC_StorageResolve
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the MqContextS instance to work on |
[out] | otherCtxP_out | the ctx of the resolve |
[out] | otherLIdP_out | the transLId of the resolve |
rbmqmsgque is using a class-attribute as instance-storage.
MqDumpC CLASS | |||
Export | MqDumpC - Export class functions … | ||
Introspection | MqDumpC - Introspection class functions … | ||
Misc | MqDumpC - Misc class functions … | ||
MqDumpC TOR | |||
Export | create a MqDumpC as export of the ctx-read-data-package … | ||
BinSet | create an MqDumpS object from binary data | ||
Error | export the context->error into the dump-package … | ||
new | create a MqDumpC as export of the ctx-read-data-package … | ||
Delete | Destructor - delete a MqDumpC instance … | ||
BinGet | export the binary data from an MqDumpS object | ||
Import | import the dump-package into the ctx-read-data-package … | ||
MqDumpC MISC | |||
Log | log the MqDumpC … | ||
SizeGet | report the binary data size from an MqDumpS object | ||
TokenGet | return the MqContextC_ServiceApi_Identifer … |
C-API: MqDumpC_C_API - MqDumpC - the class known as dmp or dump is used to export a rbmqmsgque data package as binary …
The dump is used to exchange data with external counterparts such as a database or a user-specific infrastructure.
There are 3 different function that deal with a dump:
HandleResolve | Handle-Resolve-Slot - return a MqDumpC from netHdl or nil if invalid… | ||
HandleGet | Handle-Get-Slot - returns a export-hdl to the MqDumpC useable for external storage |
Instances | get head-instance from linked-list of MqDumpS type … | ||
Next | get next instance from linked-list of MqDumpS type | ||
Prev | get previous instance from linked-list of MqDumpS type |
GetNull | Null-Slot - return a MqDumpC typed |
C-API: MqDumpC_Class_C_API - MqDumpC - define the class …
MqDumpC - Export class functions …
(static) MqDumpC MqDumpC.HandleResolve(netHdl:MK_HDL)
top Handle-Resolve-Slot - return a MqDumpC from netHdl or nil if invalid… → API: rb_mqmsgque_MqDumpC_HandleResolve
The MqDumpHandleResolve undo the MqDumpHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | netHdl | handle former exported with MqDumpHandleGet |
MK_HDL dmp.HandleGet()
top Handle-Get-Slot - returns a export-hdl to the MqDumpC useable for external storage → API: rb_mkkernel_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 MqDumpHandleResolve.
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.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | dmp | the MqDumpS instance to work on |
MqDumpC - Introspection class functions …
(static) MqDumpC MqDumpC.Instances()
top get head-instance from linked-list of MqDumpS type … → API: rb_mqmsgque_MqDumpC_Instances
The head-instance is the last instance created.
MqDumpC dmp.Next()
top get next instance from linked-list of MqDumpS type → API: rb_mqmsgque_MqDumpC_Next
MqDumpC dmp.Prev()
top get previous instance from linked-list of MqDumpS type → API: rb_mqmsgque_MqDumpC_Prev
MqDumpC - Misc class functions …
(static) MqDumpC MqDumpC.GetNull()
top Null-Slot - return a MqDumpC typed NULL
instance … → API: rb_mqmsgque_MqDumpC_GetNull
C-API: MqDumpC_TOR_C_API - MqDumpC - various functions to create, initialize and destroy a dump …
(constructor,static) MqDumpC MqDumpC.Export(ctx:MqContextC, ?dumpP_inout:MqDumpC=nil?)
top create a MqDumpC as export of the ctx-read-data-package … → API: rb_mqmsgque_MqDumpC_Export
The new instance belongs to the caller and may have to be released if necessary. A manual release using DumpDelete is always possible, but the instance can no longer be used afterwards.
The export include all data required to setup a read-data-package again later. After import with MqDumpImport the read-data-package and the environment will be set as it was on MqDumpExport The export can be saved into an external storage or be used in a network-tunnel (example: the aguard tool).
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the context to be exported into the dump-package-data |
[in,out] | dumpP_inout | returns |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
(constructor,static) MqDumpC MqDumpC.BinSet(data:binary)
top create an MqDumpS
object from binary data → API: rb_mqmsgque_MqDumpC_BinSet
Check the MqDumpC_SIGNATURE and set the refCount to 0
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | data | the binary data |
[out] | dmp_out | the new MqDumpC |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqDumpS
object is an pointer object… this mean the original data is still required and must NOT be freed.(constructor,static) MqDumpC MqDumpC.Error(error:MqContextC, ?dumpP_inout:MqDumpC=nil?)
top export the context->error into the dump-package … → API: rb_mqmsgque_MqDumpC_Error
The export include all data required to setup a read-data-package later again. After import with MqDumpImport the read-data-package and the environment will be set as it was on MqDumpExport The export can be saved into an external storage or be used in a network-tunnel (example: the agurad tool).
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | error | the error-context to be exported into the dump-package-data |
[in,out] | dumpP_inout | the dump-error-package-data to save |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
(constructor,static) MqDumpC MqDumpC.new(ctx:MqContextC, ?dumpP_inout:MqDumpC=nil?)
top create a MqDumpC as export of the ctx-read-data-package … → API: rb_mqmsgque_MqDumpC_new
The new instance belongs to the caller and may have to be released if necessary. A manual release using DumpDelete is always possible, but the instance can no longer be used afterwards.
The export include all data required to setup a read-data-package again later. After import with MqDumpImport the read-data-package and the environment will be set as it was on MqDumpExport The export can be saved into an external storage or be used in a network-tunnel (example: the aguard tool).
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ctx | the context to be exported into the dump-package-data |
[in,out] | dumpP_inout | returns |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
(destructor) dmp.Delete()
top Destructor - delete a MqDumpC instance … → API: MqDumpDelete_RT
binary dump.BinGet()
top export the binary data from an MqDumpS
object → API: rb_mqmsgque_MqDumpC_BinGet
[in] | dump | the source object |
MqDumpS
object… do NOT free. dump.Import(ctx:MqContextC)
top import the dump-package into the ctx-read-data-package … → API: rb_mqmsgque_MqDumpC_Import
The dump is the result of a previous MqDumpExport function call. After the load an package is suitable for all kind of MqContextC READ API function. To just forward the package use the MqProxyForward function.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | dump | the dump-package to be imported |
[in] | ctx | the context in wich the dump-package is imported |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
C-API: MqDumpC_Misc_C_API - MqDumpC - various functions to work on a dump …
dmp.Log(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the MqDumpC … → API: rb_mkkernel_MkObjectC_Log
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | dmp | the MqDumpS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
long dump.SizeGet()
top report the binary data size from an MqDumpS
object → API: rb_mqmsgque_MqDumpC_SizeGet
[in] | dump | the source object |
string dump.TokenGet()
top return the MqContextC_ServiceApi_Identifer … → API: rb_mqmsgque_MqDumpC_TokenGet
MqFactoryC CLASS | |||
Export | MqFactoryC - Export class functions … | ||
Introspection | MqFactoryC - Introspection class functions … | ||
Misc | MqFactoryC - Misc class functions … | ||
MqFactoryC TOR | |||
Add | add a new MqFactoryC identified by factory-identifier and defined by factory-constructor … | ||
new | add a new MqFactoryC identified by factory-identifier and defined by factory-constructor … | ||
Delete | Destructor - delete a MqFactoryC instance … | ||
Dup2 | create a duplicate of the singleton object MqFactoryC using a new factory-identifer | ||
MqFactoryC GET | |||
Get | return the MqFactoryC | ||
GetCalled | returns the MqFactoryC identified by ident … | ||
GetCalledL | returns the MqFactoryC identified as first argument in the largs MkBufferListC … | ||
GetOriginalIdent | helper function to return MqFactoryS::originalIdent | ||
MqFactoryC MISC | |||
DefaultIdent | return the factory-identifier of the default MqFactoryC | ||
InitialIdent | return the factory-identifier of the initial MqFactoryC | ||
LogAll | log all "factories" to stderr | ||
Default | set the default-attribute to the factory … | ||
Initial | set the initial-attribut to fct … | ||
Log | log the MqFactoryC … | ||
New | create a new MqContextC from a MqFactoryC … |
C-API: MqFactoryC_C_API - MqFactoryC - the class known as fct or factory is used to provide an interface to create one or more new MqContextC …
The factory is an important part of the object management and has the following basic features:
Without a factory only the pipe-feature without the child-feature is guaranteed to work. Other features may work, this depends of the "flexibility" of the programming-language.
The link between the MqFactoryS-identifier and the MqFactoryC is important for the future development of rbmqmsgque. Message-Routing, Service-Location and Persistent-Transactions depend on this feature.
The relationship between the MqFactoryC and the MqContextC is the same as the relationship between a type (MqFactoryS) and an object (MqContextS) of a regular programming language. The MqFactoryC define the type of the server and the MqContextC define a single object of the server process or thread.
Application |-------------------------------------------------------------------------------------| |--------------- physical host 1 -----------------------|------ physical host 2 ------| |-------- process-1 --------|-------- process-2 --------|-- process-3 --|---- … ------| thread-1 thread-2… thread-1… thread-2… thread-1… thread-… factory-A factory-X factory-Y… factory-Z… object-1 object-1 object-… … object-2 object-2 … object-3 object-3 … …
A server has a single MqFactoryC object per thread or process but multiple MqFactoryC objects per application. Decreasing the size and the complexity of a MqContextC object will improve the server performance. In future more fields, defined in the MqSetupS attribute of the the MqContextC object, will move into MqFactoryC object.
HandleResolve | Handle-Resolve-Slot - return a MqFactoryC from netHdl or nil if invalid… | ||
HandleGet | Handle-Get-Slot - returns a export-hdl to the MqFactoryC useable for external storage |
MqFactoryC CLASS INTROSPECTION
Instances | get head-instance from linked-list of MqFactoryS type … | ||
Next | get next instance from linked-list of MqFactoryS type | ||
Prev | get previous instance from linked-list of MqFactoryS type |
GetNull | Null-Slot - return a MqFactoryC typed |
C-API: MqFactoryC_Class_C_API - MqFactoryC - define the class …
MqFactoryC - Export class functions …
(static) MqFactoryC MqFactoryC.HandleResolve(netHdl:MK_HDL)
top Handle-Resolve-Slot - return a MqFactoryC from netHdl or nil if invalid… → API: rb_mqmsgque_MqFactoryC_HandleResolve
The MqFactoryHandleResolve undo the MqFactoryHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | netHdl | handle former exported with MqFactoryHandleGet |
MK_HDL fct.HandleGet()
top Handle-Get-Slot - returns a export-hdl to the MqFactoryC useable for external storage → API: rb_mkkernel_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 MqFactoryHandleResolve.
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.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | fct | the MqFactoryS instance to work on |
MqFactoryC - Introspection class functions …
(static) MqFactoryC MqFactoryC.Instances()
top get head-instance from linked-list of MqFactoryS type … → API: rb_mqmsgque_MqFactoryC_Instances
The head-instance is the last instance created.
MqFactoryC fct.Next()
top get next instance from linked-list of MqFactoryS type → API: rb_mqmsgque_MqFactoryC_Next
MqFactoryC fct.Prev()
top get previous instance from linked-list of MqFactoryS type → API: rb_mqmsgque_MqFactoryC_Prev
MqFactoryC - Misc class functions …
(static) MqFactoryC MqFactoryC.GetNull()
top Null-Slot - return a MqFactoryC typed NULL
instance … → API: rb_mqmsgque_MqFactoryC_GetNull
C-API: MqFactoryC_TOR_C_API - MqFactoryC - various functions to create, initialize and destroy a factory …
(constructor,static) MqFactoryC MqFactoryC.Add(constructor:class, ?ident:string="MK_NULL"?)
top add a new MqFactoryC identified by factory-identifier and defined by factory-constructor … → API: rb_mqmsgque_MqFactoryC_Add
The factory is required to get all rbmqmsgque features.
The constructor have to be a Ruby [class] with superclass [MqContextC] …
Example from Filter5.rb
→ create a new context using factory F1; F2 or F3 read from the commandline
# create buffer-list of the application arguments largv = MkBufferListC.CreateLA(ARGV) # add factories MqFactoryC.Add(F1) MqFactoryC.Add(F2) MqFactoryC.Add(F3) # select factory using the !first! application argument # and create a new server srv = MqFactoryC.GetCalledL(largv).New() begin # configure and start the server srv.LinkCreate(largv) # start event-loop and wait forever srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex # set the libmqmsgque error from the ruby error srv.ErrorCatch(ex) ensure # exit aplication and cleanup the environment srv.Exit() end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | error | (C-API) flag to signal how to report an error. valid values are: MK_ERROR_PANIC, MK_ERROR_PRINT, MK_ERROR_IGNORE or an other MqContextC |
[in] | ident | the factory-identifier, if nil or EMPTY the class-name is used. The ident is the public identifier (name) of the factory and is used in logging-output (MqLog...) , name-resolution (MqFactoryGet...) and an first parameter in the executable-call: myserver ident ... . |
[in] | createCallF | (C-API) object constructor function |
[in] | constructor | object (class) constructor data |
[in] | createDataFreeF | (C-API) object constructor data free function |
[in] | createDataCopyF | (C-API) object copy-constructor data free function |
[in] | deleteCallF | (C-API) object destructor function |
[in] | destructor | object (class) destructor data |
[in] | deleteDataFreeF | (C-API) object destructor data free function |
[in] | deleteDataCopyF | (C-API) object copy-constructor data free function |
(constructor,static) MqFactoryC MqFactoryC.new(constructor:class, ?ident:string="MK_NULL"?)
top add a new MqFactoryC identified by factory-identifier and defined by factory-constructor … → API: rb_mqmsgque_MqFactoryC_new
The factory is required to get all rbmqmsgque features.
The constructor have to be a Ruby [class] with superclass [MqContextC] …
Example from Filter5.rb
→ create a new context using factory F1; F2 or F3 read from the commandline
# create buffer-list of the application arguments largv = MkBufferListC.CreateLA(ARGV) # add factories MqFactoryC.Add(F1) MqFactoryC.Add(F2) MqFactoryC.Add(F3) # select factory using the !first! application argument # and create a new server srv = MqFactoryC.GetCalledL(largv).New() begin # configure and start the server srv.LinkCreate(largv) # start event-loop and wait forever srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex # set the libmqmsgque error from the ruby error srv.ErrorCatch(ex) ensure # exit aplication and cleanup the environment srv.Exit() end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | error | (C-API) flag to signal how to report an error. valid values are: MK_ERROR_PANIC, MK_ERROR_PRINT, MK_ERROR_IGNORE or an other MqContextC |
[in] | ident | the factory-identifier, if nil or EMPTY the class-name is used. The ident is the public identifier (name) of the factory and is used in logging-output (MqLog...) , name-resolution (MqFactoryGet...) and an first parameter in the executable-call: myserver ident ... . |
[in] | createCallF | (C-API) object constructor function |
[in] | constructor | object (class) constructor data |
[in] | createDataFreeF | (C-API) object constructor data free function |
[in] | createDataCopyF | (C-API) object copy-constructor data free function |
[in] | deleteCallF | (C-API) object destructor function |
[in] | destructor | object (class) destructor data |
[in] | deleteDataFreeF | (C-API) object destructor data free function |
[in] | deleteDataCopyF | (C-API) object copy-constructor data free function |
(destructor) fct.Delete()
top Destructor - delete a MqFactoryC instance … → API: MqFactoryDelete_RT
The factory-delete is more a pseudo-delete because a factory is always in-duty:
(constructor) MqFactoryC fct.Dup2(ident:string)
top create a duplicate of the singleton object MqFactoryC using a new factory-identifer → API: rb_mqmsgque_MqFactoryC_Dup2
C-API: MqFactoryC_Get_C_API - MqFactoryC - various functions to 'get' data out of a factory …
(static) MqFactoryC MqFactoryC.Get(?ident:string=""?)
top return the MqFactoryC → API: rb_mqmsgque_MqFactoryC_Get
The ident is the factory-name used with MqFactoryAdd - usually the class-name.
The following ident are also supported:
"initial" | belongs to the factory with MqFactoryInitial |
"default" or "" | belongs to the factory with MqFactoryDefault |
[in] | ident | the factory-identifier to search for |
(static) MqFactoryC MqFactoryC.GetCalled(?ident:string=""?)
top returns the MqFactoryC identified by ident … → API: rb_mqmsgque_MqFactoryC_GetCalled
If multiple factories (MqFactoryAdd) are available the startup code have to choose which factory to use.
The selection is done by the factory-identifer and is taken from the ident or from the first argument of the commandline-arguments-list.
[in] | ident | the factory-identifier or "" for the default MqFactoryC |
(static) MqFactoryC MqFactoryC.GetCalledL(largs:MkBufferListC)
top returns the MqFactoryC identified as first argument in the largs MkBufferListC … → API: rb_mqmsgque_MqFactoryC_GetCalledL
Like MqFactoryGetCalled but the ident is taken from the MkBufferListC object that was created from the commandline-arguments-list.
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | largs | the command-line-args or "" for the default MqFactoryC |
string fct.GetOriginalIdent()
top helper function to return MqFactoryS::originalIdent → API: rb_mqmsgque_MqFactoryC_GetOriginalIdent
C-API: MqFactoryC_Misc_C_API - MqFactoryC - various functions to work on a factory …
(static) string MqFactoryC.DefaultIdent()
top return the factory-identifier of the default MqFactoryC → API: rb_mqmsgque_MqFactoryC_DefaultIdent
(static) string MqFactoryC.InitialIdent()
top return the factory-identifier of the initial MqFactoryC → API: rb_mqmsgque_MqFactoryC_InitialIdent
(static) MqFactoryC.LogAll(?callfunc:string="MK_NULL"?)
top log all "factories" to stderr → API: rb_mqmsgque_MqFactoryC_LogAll
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
MqFactoryC fct.Default()
top set the default-attribute to the factory … → API: rb_mqmsgque_MqFactoryC_Default
The default-factory is used to create an MqFactoryC if MqFactoryGetCalled was not able to find a specific factory object. This is designed for a scenario with multiple factories included into a single binary and the first commandline parameter after the executable name… (position 0=executable, position 1=factory-selector)… is not related to a factory-ident… added with MqFactoryAdd.
[in] | fct | the new default MqFactoryC |
Example: from example/rb/server.cs
MqFactoryC fct.Initial()
top set the initial-attribut to fct
… → API: rb_mqmsgque_MqFactoryC_Initial
The factory with "Initial"-attribute is always used for an object that should only be created with the MqContextC base class, but for which no other factory has been specified.
Use this attribute with care because you are firmly linking a factory. In a programming language with class-support, such as C++ or C#, this class is used for every new MqContextC object.
Where "Reflection" is available, this attribute has less meaning since the class is primarily determined from the parent object by means of "Reflection".
The "Initial" attribute is otherwise used for the "Loopback" and the "Filter" capability.
Example from Filter4.rb
→ set Initial attribute to a Factory
MqFactoryC.Add(Filter4).Initial # "srv" get the "Initial" factory srv = Filter4.new begin srv.LinkCreate(ARGV) srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex srv.ErrorCatch(ex) ensure srv.Exit() end
[in] | fct | the new initial MqFactoryC |
fct.Log(?fmtobj:MkObjectC=nil?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the MqFactoryC … → API: rb_mkkernel_MkObjectC_Log
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | fct | the MqFactoryS instance to work on |
[in] | fmtobj | managed object used to format the log-message (default=nil → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling function or the environment (default=name-of-function ) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
MqContextC fct.New()
top create a new MqContextC from a MqFactoryC … → API: rb_mqmsgque_MqFactoryC_New
this create only the initial-server-object… all other server-objects will be created on behalf of the client-request.
Example from MyServer.rb
→ create a new server context
require "rbmqmsgque" include RbMsgque::MqMsgque # package-item class MyServer < MqContextC # factory startup def initialize() super ConfigSetServerSetup(method(:ServerSetup)) end # define a service as link between the token "HLWO" and the callback "MyFirstService" def ServerSetup ServiceCreate("HLWO",method(:MyFirstService)) end # service to serve all incoming requests for token "HLWO" def MyFirstService() SendSTART() SendSTR(ReadSTR() + " World") SendRETURN() end end # ==================================================== # package-main # create the "MyServer" factory… and object srv = MqFactoryC.Add(MyServer).New() begin srv.LinkCreate(ARGV) srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex srv.ErrorCatch(ex) ensure srv.Exit() end
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | fct | a MqFactoryC used to create a MqContextC |
[in] | tmpl | (C-API only) template for context intialization |
[out] | val_out | the new context object as return or nil on error |
C-API: MqContextC_FilterApi_C_API - MqContextC - modify the data using the filter-technology …
The filter mode is related to a special usage of the rbmqmsgque software called a command pipeline. To define a filter create a server with:
Every filter has two context one belongs to the left command and one belongs to the right command:
<-- left cmd --> <------- filter -------> <-- right cmd --> <-- left --><- right --> <- server -><- client -> <- master -><- slave --> <-context1-><-context2-> ... command1 @ filter @ command2 ...
The left context is created on application startup and the right context is created as slave of the left context.
client @ filter @ server
<------------ host-1 -------------> <-- network --> <---------- host-2 -----------> <---- client arguments ----> <--- server arguments --> <-- filter arg. --> <--- options ---> client @ filter @ --tcp --port 7777 ........... server --tcp --port 7777 --fork
A bi-directional filter allow a data-flow in both directions and is used in a classical client/server application:
client ... <--> ... server
as a feature enhancement like a protocol-tunnelling:
client @ mq2tunnel ... <--> ... tunnel2mq @ server
or to convert the protocol into an other protocol:
client @ mq2soap ... <--> ... soap-server
To define a bi-directional filter a couple of commands provide support:
aguard
)aguard
), or to save the body in a persistent storage for later use MqDumpImport.A one-directional filter is a special form of a bi-directional filter and allow a data-flow from the left to the right.
This filter is well known from the unix shell to link different commands together:
command1 | command2 | command3
A rbmqmsgque command pipeline is created with the special character "@" instead of "|" :
msgcmd1 @ msgcmd2 @ msgcmd3
To define a rbmqmsgque filter... create a service handle with MqServiceCreate or MqServiceProxy ... using the token +FTR and +EOF
token | description |
---|---|
+FTR | required to act on filter data rows. Every filter input data is a list of filter data rows and every row is a list of filter data columns. Every row is send to the following filter-command as +FTR service request |
+EOF | required to act on End-Of-Filter data and is called after all +FTR data was send. Sometimes the filter data can not be served as +FTR data (example: sorting of the input rows need to read all rows before the data can be send to the next filter command) and the+EOF token is used to continue send +FTR data rows. |
and send every data item with MqSendEND_AND_WAIT .
This library is actively developed and tested on x86_64 Linux (opensuse), older versions have also been successful tested on FreeBSD, WindowsXP/7, MacOSX and Solaris using x86_64, i686, ppc and sparc processor.
mulserver.rb
→ require "rbmqmsgque" include RbMsgque::MqMsgque class MulServer < MqContextC def initialize() super() ConfigSetServerSetup(method(:ServerSetup)) end def MMUL SendSTART() SendDBL(ReadDBL() * ReadDBL()) SendRETURN() end def ServerSetup() ServiceCreate("MMUL",method(:MMUL)) end end srv = MqFactoryC.Add(MulServer,"mulserver").New() begin srv.LinkCreate(ARGV) srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex srv.ErrorCatch(ex) ensure srv.Exit() end
mulclient.rb
→ require "rbmqmsgque" include RbMsgque::MqMsgque ctx = MqContextC.new begin ctx.ConfigSetName("MyMul") ctx.LinkCreate(ARGV) ctx.SendSTART() ctx.SendDBL(3.67) ctx.SendDBL(22.3) ctx.SendEND_AND_WAIT("MMUL") $stdout.puts ctx.ReadDBL() rescue Exception => ex ctx.ErrorCatch(ex) ensure ctx.Exit() end
MyLoopServer.rb
→ require "rbmqmsgque" include RbMsgque::MqMsgque # package-item class MyLoopServer < MqContextC attr_reader :mydata # factory startup def initialize() super() ConfigSetServerSetup(method(:ServerSetup)) # set the "mydata" attribute to the master-context @mydata = "Hello World" end # service to serve all EXTERNAL requests for token "HLWO" def HLWO_srv # get the "loopback" context loop = SlaveGet(MqSlaveE::LOOPBACK) # call the LOOP service on the SAME server loop.Send("W","LOOP") # answer HLWO with string-return from LOOP Send("R", "C", loop.ReadSTR()) end # service to serve all INTERNAL requests for token "LOOP" def LOOP_srv(loop) # get the "master" context master = loop.SlaveGetMaster() # answer LOOP with data from MASTER->mydata attribute loop.Send("R", "C", master.mydata) end # define a service as link between the token "HLWO" and the callback "HLWO_srv" def ServerSetup loop = SlaveGet(MqSlaveE::LOOPBACK) # EXTERNAL: link the "HLWO" service with "HLWO_srv" ServiceCreate("HLWO",method(:HLWO_srv)) # INTERNAL: link the "LOOP" service with "LOOP_srv" loop.ServiceCreate("LOOP",method(:LOOP_srv)) end end # ==================================================== # package-main # create the "MyLoopServer" factory… and the instance srv = MqFactoryC.Add(MyLoopServer).New() begin srv.LinkCreate(ARGV) srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue Exception => ex srv.ErrorCatch(ex) ensure srv.Exit() end
MyClient.rb
→ require "rbmqmsgque" include RbMsgque::MqMsgque ctx = MqContextC.new begin ctx.ConfigSetName("MyClient") ctx.LinkCreate(ARGV) ctx.SendSTART() ctx.SendSTR "Hello" ctx.SendEND_AND_WAIT("HLWO") puts ctx.ReadSTR() rescue Exception => ex ctx.ErrorCatch(ex) ensure ctx.Exit() end
Example from manfilter.rb
→
require "rbmqmsgque" include RbMsgque::MqMsgque class ManFilter < MqContextC def initialize super() ConfigSetName("filter") ConfigSetServerSetup(method(:ServerSetup)) end def ServerSetup ServiceCreate("+FTR", method(:FTRcmd)) ServiceProxy("+EOF") end def FTRcmd ftr = SlaveGetFilter() ftr.SendSTART() while ReadItemExists() ftr.SendSTR("<" + ReadSTR() + ">") end ftr.SendEND_AND_WAIT("+FTR") SendRETURN() end end srv = ManFilter.new begin srv.LinkCreate(ARGV) srv.ProcessEvent(MqWaitOnEventE::FOREVER) rescue SignalException => ex # ignore rescue Exception => ex srv.ErrorCatch(ex) ensure srv.Exit() end
Use manfilter.rb in a rbmqmsgque command pipeline:
libmqmsgque, ccmqmsgque, csmqmsgque, javamqmsgque, gomqmsgque, pymqmsgque, rbmqmsgque, tclmqmsgque, perlmqmsgque, phpmqmsgque
Ruby, unix, socket, message, msgque