theLink 10.0
|
A library to connect things, run a server and integrate your application.
The atlmqmsgque package is the implementation of the Programming-Language-Micro-Kernel (PLMK) into the target-language Atl.
package require atlmqmsgque
The atlmqmsgque package is a composition of multiple classes defining the Programming-Language-Micro-Kernel (PLMK) :
object | description |
---|---|
MqMsgque | the namespace with all atlmqmsgque specific definitions |
MqMsgque::Attribute | the interface to access the package specific attribute |
MqClassC::Attribute | the interface to access the class specific attribute |
MqClassC::Attribute $Instance | the interface to access the instance specific attribute |
To access all features without MqMsgque prefix use:
namespace path [list MqMsgque ClassC ...] → The ATL is 'namespace-based' and TCL does not support a 'namespace-import' into an other namespace. → By default the PACKAGE '::MqMsgque' and the '::ClassC' is defined in the GLOBAL namespace. → By default the ATTRIBUTE is always reachable by '::MqMsgque::attribute' and '::ClassC::attribute'.
libatlmqmsgque.so
libatlmqmsgque.la
To access the atlmqmsgque package the environment variable TCLLIBPATH
have to include the directory.
TCLLIBPATH If set, then it must contain a valid Tcl list giving directories to search during auto-load operations. Directories must be specified in Tcl format, using “/” as the path separator, regardless of platform. This variable is only used when initializing the auto_path variable.
::pkg::create is a utility procedure that is part of the standard Tcl library. It is used to create an appropriate `package ifneeded` command for a given package specification. It can be used to construct a `pkgIndex.tcl` file for use with the package mechanism.
pkgIndex.tcl
file is simplepackage ifneeded NAME 9.0 [list load [file join $dir libNAME.so]]
namespace path ?namespaceList?
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 atlmqmsgque internal memory … | ||
Setup | setup atlmqmsgque 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 atlmqmsgque specific user-help to stderr | ||
HelpMsgque | return a page with the usage of all atlmqmsgque 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 | ||
MqMsgque MAIN | |||
Main | Main entrypoint - start the application |
C-API: MqMsgque_C_API - MqMsgque PACKAGE - the package is the toplevel structure of the atlmqmsgque …
The atlmqmsgque package is loaded with:
package require atlmqmsgque
and is a composition of one or more package-item and exact one package-main.
The atlmqmsgque 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 atlmqmsgque 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 atlmqmsgque package add the following types into MkObjectC_C_API :
ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType) | |- ABSTRACT: MqTypeCtxC_TT (TypeType = type of a Type) | | | |- MqContextC_T | |- ABSTRACT: MkTypeDefSTT (TypeType = type of a Type) | |- MqFactoryST, MqDumpST
C-API: MqMsgque_Setup_C_API - MqMsgque PACKAGE - setup und cleanup the atlmqmsgque …
For details about MqSetup and MqCleanup usage refer to MkKernel_Setup_libmkkernel_C_API
(static) MqMsgque::Cleanup
top cleanup atlmqmsgque internal memory … → API: atlmqmsgque_MqMsgque_Cleanup
Cleanup will only be recognized once and will be ignored if not called in the same thread as Setup. After a call to Setup the call to MkCleanup is possible again.
gcc: __attribute__ ((cleanup(XXX)))
is called when unloading the library.(static) MqMsgque::Setup
top setup atlmqmsgque internal memory … → API: atlmqmsgque_MqMsgque_Setup
Setup will only be recognized once, additional call's will be ignored until a Cleanup is called.
gcc: __attribute__ ((constructor(XXX)))
is called when loading the library.dlopen
and additionally uses threads, a manual call to Setup very early at startup is required to enforce the correct order of type declarations. 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: atlmqmsgque_Get_MqIdentE_FromObj
(static) MqIdentE [MqMsgque::IdentE_FromInt value:int32]
top return the MqIdentE from integer … → API: atlmqmsgque_MqMsgque_IdentE_FromInt
(static) int32 [MqMsgque::IdentE_ToInt value:MqIdentE]
top return the MqIdentE as integer … → API: atlmqmsgque_MqMsgque_IdentE_ToInt
(static) string [MqMsgque::IdentE_ToString value:MqIdentE]
top return the MqIdentE as string … → API: atlmqmsgque_MqMsgque_IdentE_ToString
top predefined slave-id for well known slaves … → API: atlmqmsgque_Get_MqSlaveE_FromObj
(static) MqSlaveE [MqMsgque::SlaveE_FromInt value:int32]
top return the MqSlaveE from integer … → API: atlmqmsgque_MqMsgque_SlaveE_FromInt
(static) int32 [MqMsgque::SlaveE_ToInt value:MqSlaveE]
top return the MqSlaveE as integer … → API: atlmqmsgque_MqMsgque_SlaveE_ToInt
(static) string [MqMsgque::SlaveE_ToString value:MqSlaveE]
top return the MqSlaveE as string … → API: atlmqmsgque_MqMsgque_SlaveE_ToString
top User preferences on HOWTO start a new entity. → API: atlmqmsgque_Get_MqStartE_FromObj
(static) MqStartE [MqMsgque::StartE_FromInt value:int32]
top return the MqStartE from integer … → API: atlmqmsgque_MqMsgque_StartE_FromInt
(static) int32 [MqMsgque::StartE_ToInt value:MqStartE]
top return the MqStartE as integer … → API: atlmqmsgque_MqMsgque_StartE_ToInt
(static) string [MqMsgque::StartE_ToString value:MqStartE]
top return the MqStartE as string … → API: atlmqmsgque_MqMsgque_StartE_ToString
top Information about how the context was created. → API: atlmqmsgque_Get_MqStatusIsEF_FromObj
(static) MqStatusIsEF [MqMsgque::StatusIsEF_FromInt value:int32]
top return the MqStatusIsEF from integer … → API: atlmqmsgque_MqMsgque_StatusIsEF_FromInt
(static) int32 [MqMsgque::StatusIsEF_ToInt value:MqStatusIsEF]
top return the MqStatusIsEF as integer … → API: atlmqmsgque_MqMsgque_StatusIsEF_ToInt
(static) string [MqMsgque::StatusIsEF_ToString value:MqStatusIsEF]
top return the MqStatusIsEF as string … → API: atlmqmsgque_MqMsgque_StatusIsEF_ToString
top wait for an event? … → API: atlmqmsgque_Get_MqWaitOnEventE_FromObj
(static) MqWaitOnEventE [MqMsgque::WaitOnEventE_FromInt value:int32]
top return the MqWaitOnEventE from integer … → API: atlmqmsgque_MqMsgque_WaitOnEventE_FromInt
(static) int32 [MqMsgque::WaitOnEventE_ToInt value:MqWaitOnEventE]
top return the MqWaitOnEventE as integer … → API: atlmqmsgque_MqMsgque_WaitOnEventE_ToInt
(static) string [MqMsgque::WaitOnEventE_ToString value:MqWaitOnEventE]
top return the MqWaitOnEventE as string … → API: atlmqmsgque_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 atlmqmsgque specific user-help to stderr → API: atlmqmsgque_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 atlmqmsgque specific options → API: atlmqmsgque_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: atlmqmsgque_MqMsgque_InitGetArg0
"MK_NULL"
pointer (static) MkBufferListC [MqMsgque::InitResetArg0]
top Reset the process-startup-prefix argument to an empty list … → API: atlmqmsgque_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 atlmqmsgque and have not to be initialized again.
Example from server.atl
→ initialize the startup-prefix with the data read from service-args
proc Ot_INIT { myNs } { SendSTART $myNs MqMsgque::InitSetArg0 [ReadALL $myNs] SendRETURN $myNs }
(static) MqMsgque::InitSetArg0 ?bfl:MkBufferListC...=NULL?
top set the process startup-prefix argument to bfl → API: atlmqmsgque_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 |
C-API: MqMsgque_Main_C_API - MqMsgque PACKAGE - the package-main is a single piece of code evaluated only once at application startup …
Example from MyServer.atl
→ The package-main configure the factory and start the server.
package require lib_85 package require atlmqmsgque # package-item ::myooX::ClassN ::MyServer { SuperI ::MqContextC # service to serve all incoming requests for token "HLWO" proc myFirstService {myNs} { SendSTART $myNs SendSTR $myNs "[ReadSTR $myNs] World" SendRETURN $myNs } # define a service as link between the token "HLWO" and the callback "MyFirstService" proc serverSetup {myNs} { ServiceCreate $myNs "HLWO" myFirstService } # factory startup (constructor) proc MyServer {myNs {tmpl ""}} { MqContextC $myNs $tmpl ConfigSetServerSetup $myNs serverSetup } } # package-main MqMsgque::Main { # setup commandline arguments for later use set args [MkBufferListC::CreateLA {*}$argv] # create "MyServer" factory... and make it to the default. set fct [MqFactoryC::Default [MqFactoryC::Add ::MyServer]] # inspect commandline-argument for the "factory" to choose... and create a object set fct [MqFactoryC::GetCalledL $args] set srv [MqFactoryC::New $fct] try { MqContextC::LinkCreate $srv $args MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
(static) MqMsgque::Main code:...
top Main entrypoint - start the application → API: MqMain
Tcl has a special requirement, for every new server-thread a new interpreter is created and
this interpreter source the toplevel file for initialization. This file is set on library startup and
can be changed with MqInitResetArg0. The problem is the server startup code from the toplevel. For internal
purpose this code should only be executed on application-startup (like the C main function)
and not for every thread again.
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 ... | ||
CTOR | 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 |
MqServerSetupIF | define the server-setup-interface (callback) used on startup … |
ServiceCreate | create a link between a service-token and a service-callback … |
MqServerCleanupIF | 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=NULL?] | myooX::NewN ::MqContextC ?tmpl:MqContextC=""? |
(destructor) MqContextC::Delete $ctx | myooX::DeleteN $ctx |
HandleResolve | Handle-Resolve-Slot - return a MqContextC from netHdl or "MK_NULL" 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 "MK_NULL"
if invalid… → API: atlmqmsgque_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_NULL"
if netHdl is invalid MK_HDL [MqContextC::HandleGet $ctx]
top Handle-Get-Slot - returns a export-hdl to the MqContextC useable for external storage → API: atlmkkernel_MkObjectC_HandleGet
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MqContextHandleResolve.
By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
[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: atlmqmsgque_MqContextC_Instances
The head-instance is the last instance created.
MqContextC [MqContextC::Next $ctx]
top get next instance from linked-list of MqContextS type → API: atlmqmsgque_MqContextC_Next
MqContextC [MqContextC::Prev $ctx]
top get previous instance from linked-list of MqContextS type → API: atlmqmsgque_MqContextC_Prev
MqContextC - Misc class functions …
(static) MqContextC [MqContextC::GetNull]
top Null-Slot - return a MqContextC typed NULL
instance … → API: atlmqmsgque_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=NULL?]
top create and initialize the MqContextC ... → API: atlmqmsgque_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.atl
→ create a context using the static atlmqmsgque CTOR
package require lib_85 package require atlmqmsgque # create a context using the static atlmqmsgque CTOR method "Create" set ctx [MqContextC::Create] try { MqContextC::ConfigSetName $ctx "MyClient" MqContextC::LinkCreate $ctx {*}$argv MqContextC::SendSTART $ctx MqContextC::SendSTR $ctx "Hello" MqContextC::SendEND_AND_WAIT $ctx "HLWO" puts [MqContextC::ReadSTR $ctx] } on error {} { MqContextC::ErrorCatch $ctx } finally { # delete the context using the atlmqmsgque APPLICATION-DTOR method "Exit" MqContextC::Exit $ctx }
[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: "MK_NULL" , reuse the MkTypeSTT from tmpl or use MqContextC_T if tmpl = "MK_NULL" ) |
[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: "MK_NULL" , create an initial context) |
(constructor,static) MqContextC [MqContextC::CTOR ?tmpl:MqContextC=NULL?]
top create and initialize the MqContextC ... → API: atlmqmsgque_MqContextC_CTOR
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.atl
→ create a context using the static atlmqmsgque CTOR
package require lib_85 package require atlmqmsgque # create a context using the static atlmqmsgque CTOR method "Create" set ctx [MqContextC::Create] try { MqContextC::ConfigSetName $ctx "MyClient" MqContextC::LinkCreate $ctx {*}$argv MqContextC::SendSTART $ctx MqContextC::SendSTR $ctx "Hello" MqContextC::SendEND_AND_WAIT $ctx "HLWO" puts [MqContextC::ReadSTR $ctx] } on error {} { MqContextC::ErrorCatch $ctx } finally { # delete the context using the atlmqmsgque APPLICATION-DTOR method "Exit" MqContextC::Exit $ctx }
[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: "MK_NULL" , reuse the MkTypeSTT from tmpl or use MqContextC_T if tmpl = "MK_NULL" ) |
[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: "MK_NULL" , create an initial context) |
(destructor) MqContextC::Delete $ctx
top Destructor - delete a MqContextC instance … → API: MqContextDelete_RT
Shutdown the client-server-link, free the memory and set the ctx to "MK_NULL"
. The context can not be reused.
Example from MyClient2.atl
→ delete a application-context using the atlmqmsgque 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_Class_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 [MqContextC::ClassFactoryGet $ctx]
top get the MqFactoryC used by the MqContextC → API: atlmqmsgque_MqContextC_ClassFactoryGet
[in] | ctx | the MqContextC to extract the MqFactoryC from |
MqContextC::ClassFactorySet $ctx item:MqFactoryC
top link the MqContextC to a new MqFactoryC → API: atlmqmsgque_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 [MqContextC::ClassIdentGet $ctx]
top get the application-identification … → API: atlmqmsgque_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::dispPrefix | 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::dispPrefix 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 | [[tclmqmsgque::MqFactoryC Get "initial"] Dup2 "TestClient"] Initial |
MqContextC::ClassIdentSet $ctx ident:string
top link the MqContextC to a new MqFactoryC identified by ident → API: atlmqmsgque_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 [MqContextC::ClassOriginalIdentGet $ctx]
top get the MqFactoryS::originalIdent from the MqContextC → API: atlmqmsgque_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 "MK_NULL" | ||
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::dispPostfix | ||
ConfigGetPrefix | get the MqConfigS::dispPrefix | ||
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 | ||
ConfigSetAllTimeout | set the MqIoConfigS::timeout 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: MqContextC::ConfigSetConfigFile $ctx 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:
MqContextC::ConfigSetName $ctx data:string
, MqContextC::ConfigSetPrefix $ctx data:string
, MqContextC::ConfigSetPostfix $ctx data:string
function prefix | postfix | dispname |
---|---|---|
client | -1-1 | client-1-1 |
MqContextC::ConfigSetName $ctx data:string
or --name stringattribute: MqConfigS::dispPrefix, getter: MqContextC_ConfigGetPrefix, setter: MqContextC_ConfigSetPrefix
set the server-part (1) of the application-identifer MqConfigS::dispName …
The dispprefix is used for:
The prefix is initialize with:
MqContextC::ConfigSetPrefix $ctx data:string
or the MqContextC::ConfigSetName $ctx data:string
functionattribute: MqConfigS::dispPostfix, 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:
MqContextC::ConfigSetPostfix $ctx data:string
functionattribute: MqConfigS::storageFile, 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::dispPrefix | 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::dispPrefix 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 | [[tclmqmsgque::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: "MK_NULL" ) |
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: MqContextC::ConfigSetDaemon $ctx pidfile:string
This option is not available for atlmqmsgque.
attribute: MkLogDataS::logFILE, getter: MkRuntimeC_LogTargetGet, setter: MkRuntimeC_LogTargetSet
attribute: MkRuntimeS::isSilent, getter: MkRuntimeC_IsSilentGet, setter: MkRuntimeC_IsSilentSet
attribute: MkRuntimeS::debug, getter: MkRuntimeC_DebugGet, setter: MkRuntimeC_DebugSet
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
.
MqServerSetupIF
: 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
.
MqServerCleanupIF
: 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.
MqBgErrorIF
: 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
MqEventIF
: 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 [MqContextC::ConfigGetBuffersize $ctx]
top get the minimum of the read/send buffersize of the socket → API: atlmqmsgque_MqContextC_ConfigGetBuffersize
[in] | ctx | the MqContextS instance to work on |
context.config.buffersize
(R/S) value MqIdentE [MqContextC::ConfigGetIdentFrom $ctx]
top get the MqConfigS::identFrom → API: atlmqmsgque_MqContextC_ConfigGetIdentFrom
[in] | ctx | the MqContextS instance to work on |
prefix
or factory int32 [MqContextC::ConfigGetIoPipe $ctx]
top return the MqIoPipeConfigS → API: atlmqmsgque_MqContextC_ConfigGetIoPipe
[in] | ctx | the MqContextS instance to work on |
{host:string port:string myhost:string myport:string} [MqContextC::ConfigGetIoTcp $ctx]
top get the configuration-data of the tcp-client-server-link … → API: atlmqmsgque_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) |
"MK_NULL"
"MK_NULL"
… nothing will be done MkBufferListC [MqContextC::ConfigGetIoTcpL $ctx]
top get the configuration-data of the tcp-client-server-link as MkBufferListC … → API: atlmqmsgque_MqContextC_ConfigGetIoTcpL
host |
| ||||
port |
| ||||
myhost | name of the local interface | ||||
myport | 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 |
[out] | vals_out | the contain host, port, myhost and myport data |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
string [MqContextC::ConfigGetIoUds $ctx]
top return the MqIoUdsConfigS → API: atlmqmsgque_MqContextC_ConfigGetIoUds
[in] | ctx | the MqContextS instance to work on |
context.config.io.uds.file
value bool [MqContextC::ConfigGetIsParent $ctx]
top does the context object is a parent ? An objext is a parent id the MqConfigS::parent attribute is "MK_NULL"
→ API: atlmqmsgque_MqContextC_ConfigGetIsParent
[in] | ctx | the MqContextS instance to work on |
(ctx->config.parent == NULL)
value bool [MqContextC::ConfigGetIsServer $ctx]
top does the context object is a server ? → API: atlmqmsgque_MqContextC_ConfigGetIsServer
[in] | ctx | the MqContextS instance to work on |
(ctx->setup.isServer == true)
value bool [MqContextC::ConfigGetIsString $ctx]
top does the context object is using the string-mode ? → API: atlmqmsgque_MqContextC_ConfigGetIsString
[in] | ctx | the MqContextS instance to work on |
(ctx->config.native == 'S')
value string [MqContextC::ConfigGetName $ctx]
top get the name of the context object → API: atlmqmsgque_MqContextC_ConfigGetName
[in] | ctx | the MqContextS instance to work on |
context.config.name
value int32 [MqContextC::ConfigGetPkgsize $ctx]
top get the maximun size of a BDY package → API: atlmqmsgque_MqContextC_ConfigGetPkgsize
[in] | ctx | the MqContextS instance to work on |
context.config.pkgsize
(R/S) value string [MqContextC::ConfigGetPostfix $ctx]
top get the MqConfigS::dispPostfix → API: atlmqmsgque_MqContextC_ConfigGetPostfix
[in] | ctx | the MqContextS instance to work on |
string [MqContextC::ConfigGetPrefix $ctx]
top get the MqConfigS::dispPrefix → API: atlmqmsgque_MqContextC_ConfigGetPrefix
[in] | ctx | the MqContextS instance to work on |
MqStartE [MqContextC::ConfigGetStartAs $ctx]
top return the MqConfigS::startAs value → API: atlmqmsgque_MqContextC_ConfigGetStartAs
MqStatusIsEF [MqContextC::ConfigGetStatusIs $ctx]
top return the MqContextS::statusIs value → API: atlmqmsgque_MqContextC_ConfigGetStatusIs
string [MqContextC::ConfigGetStorage $ctx]
top get the storage of the context object → API: atlmqmsgque_MqContextC_ConfigGetStorage
[in] | ctx | the MqContextS instance to work on |
context.config.storageFile
value MkTimeoutE|int32 [MqContextC::ConfigGetTimeout $ctx]
top get the timeout value of the context object → API: atlmqmsgque_MqContextC_ConfigGetTimeout
[in] | ctx | the MqContextS instance to work on |
context.config.timeout
value MqContextC::ConfigSetConfigFile $ctx filename:string
top set the config-file and parse for well-known config-items → API: atlmqmsgque_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 MqContextC::ConfigSetBgError $ctx ?callback:callable=NULL?
top set the MqSetupS::BgError → API: atlmqmsgque_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.
MqBgErrorIF
: 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. |
MqContextC::ConfigSetEvent $ctx ?callback:callable=NULL?
top set the MqSetupS::Event → API: atlmqmsgque_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
MqEventIF
: 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. |
MqContextC::ConfigSetServerCleanup $ctx ?callback:callable=NULL?
top set the MqSetupS::ServerCleanup → API: atlmqmsgque_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
.
MqServerCleanupIF
: 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. |
MqContextC::ConfigSetServerSetup $ctx ?callback:callable=NULL?
top set the MqSetupS::ServerSetup → API: atlmqmsgque_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
.
MqServerCleanupIF
: 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 …
MqContextC::ConfigReset $ctx
top clean the MqContextS::config data → API: atlmqmsgque_MqContextC_ConfigReset
C-API: MqContextC_ConfigApi_Set_C_API - MqContextC - various function to 'set' the configuration-data in a context …
bool [MqContextC::ConfigCheckStartAs $ctx data:MqStartE]
top check if MqConfigS::startAs can be set to data → API: atlmqmsgque_MqContextC_ConfigCheckStartAs
MqContextC::ConfigSetAllDebug $ctx data:int32
top set the MkRuntimeS::debug value → API: atlmqmsgque_MqContextC_ConfigSetAllDebug
set all childs and all slaves and the link target parter… too
MqContextC::ConfigSetAllTimeout $ctx data:MkTimeoutE|int32
top set the MqIoConfigS::timeout value → API: atlmqmsgque_MqContextC_ConfigSetAllTimeout
set all childs and all slaves too
MqContextC::ConfigSetBuffersize $ctx data:int32
top set the MqIoConfigS::buffersize value → API: atlmqmsgque_MqContextC_ConfigSetBuffersize
MqContextC::ConfigSetDaemon $ctx pidfile:string
top start the server-context as daemon … → API: atlmqmsgque_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) |
MqContextC::ConfigSetIdentFrom $ctx data:MqIdentE
top set the MqConfigS::identFrom value → API: atlmqmsgque_MqContextC_ConfigSetIdentFrom
MqContextC::ConfigSetIgnoreExit $ctx data:bool
top set the MqSetupS::ignoreExit value → API: atlmqmsgque_MqContextC_ConfigSetIgnoreExit
MqContextC::ConfigSetIoPipe $ctx fh:int32
top set the pipe configuration data … → API: atlmqmsgque_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) |
MqContextC::ConfigSetIoTcp $ctx ?host:string="NULL"? ?port:string="NULL"? ?myhost:string="NULL"? ?myport:string="NULL"?
top configure a context to use a tcp-client-server-link … → API: atlmqmsgque_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) |
MqContextC::ConfigSetIoTcpL $ctx vals:MkBufferListC
top configure a context to use a tcp-client-server-link … → API: atlmqmsgque_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) |
MqContextC::ConfigSetIoUds $ctx file:string
top configure a context to use a uds-client-server-link … → API: atlmqmsgque_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: "MK_NULL" ) |
[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) |
MqContextC::ConfigSetIsServer $ctx data:bool
top set the MqSetupS::isServer value → API: atlmqmsgque_MqContextC_ConfigSetIsServer
MqContextC::ConfigSetIsString $ctx data:bool
top set the MqConfigS::native value 'S'string or 'L'owEndian or 'B'igEndian → API: atlmqmsgque_MqContextC_ConfigSetIsString
MqContextC::ConfigSetName $ctx data:string
top set the MqConfigS::dispName value and cleanup old value → API: atlmqmsgque_MqContextC_ConfigSetName
MqContextC::ConfigSetPkgsize $ctx data:int32
top set the MqIoConfigS::pkgsize value → API: atlmqmsgque_MqContextC_ConfigSetPkgsize
MqContextC::ConfigSetPostfix $ctx data:string
top set the client-part (2) of the application-identifer MqConfigS::dispName … → API: atlmqmsgque_MqContextC_ConfigSetPostfix
The postfix is used for:
The postfix is initialize with:
MqContextC::ConfigSetPostfix $ctx data:string
function MqContextC::ConfigSetPrefix $ctx data:string
top set the server-part (1) of the application-identifer MqConfigS::dispName … → API: atlmqmsgque_MqContextC_ConfigSetPrefix
The dispprefix is used for:
The prefix is initialize with:
MqContextC::ConfigSetPrefix $ctx data:string
or the MqContextC::ConfigSetName $ctx data:string
function MqContextC::ConfigSetStartAs $ctx data:MqStartE
top set the MqConfigS::startAs value → API: atlmqmsgque_MqContextC_ConfigSetStartAs
MqContextC::ConfigSetStartAsString $ctx data:string
top set the MqConfigS::startAs value using string default
, thread
, fork
or spawn
→ API: atlmqmsgque_MqContextC_ConfigSetStartAsString
MqContextC::ConfigSetStorage $ctx data:string
top set the Storage value and cleanup old value → API: atlmqmsgque_MqContextC_ConfigSetStorage
MqContextC::ConfigSetTimeout $ctx data:MkTimeoutE|int32
top set the MqIoConfigS::timeout value → API: atlmqmsgque_MqContextC_ConfigSetTimeout
EnvProtect | protect the service-environment | ||
EnvRestore | restore the service-environment |
C-API: MqContextC_EnvApi_Env_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 atlmqmsgque 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.atl
→ protect the environment and import from database
# PROTECT the original service-call EnvProtect $myNs # OVERWRITE the original service-call with data from the database MqDumpC::Import $dump $myNs set ret [ReadALL $myNs] # RESTORE the original service-call EnvRestore $myNs # ANSWER the original service-call Send $myNs "R" "L" $ret
MqContextC::EnvProtect $ctx
top protect the service-environment → API: atlmqmsgque_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 |
MqContextC::EnvRestore $ctx
top restore the service-environment → API: atlmqmsgque_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_Error_C_API - MqContextC - move and copy an error from a context …
MkErrorE [MqContextC::ErrorCopy $targetCtx sourceCtx:MqContextC]
top copy a MkErrorS from the sourceCtx to the targetCtx … → API: atlmqmsgque_MqContextC_ErrorCopy
In atlmqmsgque 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 atlmqmsgque 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 [MqContextC::ErrorFORMAT $fmtobj]
top helper used to access MkErrorDEFAULT from MqContextC → API: atlmqmsgque_MqContextC_ErrorFORMAT
MkErrorE [MqContextC::ErrorMove $targetCtx sourceCtx:MqContextC]
top move a MkErrorS from the sourceCtx to the targetCtx … → API: atlmqmsgque_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_High_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_High_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.atl
→ in a service-call send the server-configuratien back to the client
proc Ot_CNFG { myNs } { SendSTART $myNs SendBOL $myNs [ConfigGetIsServer $myNs] SendBOL $myNs [LinkIsParent $myNs] SendBOL $myNs [SlaveIs $myNs] SendBOL $myNs [ConfigGetIsString $myNs] SendBOL $myNs [MkRuntimeC::IsSilentGet] SendBOL $myNs [LinkIsConnected $myNs] SendSTR $myNs [ConfigGetName $myNs] SendI32 $myNs [MkRuntimeC::DebugGet] SendI32 $myNs [LinkGetCtxId $myNs] SendSTR $myNs [ServiceTokenGet $myNs] SendRETURN $myNs }
MqContextC::Send $ctx 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_Link_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"
MqContextC::LinkConnect $ctx
top re-connect a client-server-link after a server crash or a network downtime … → API: atlmqmsgque_MqContextC_LinkConnect
Do nothing if the client-server-link is already connected. This function is only useful in an event-function (MqEventIF) if the link-disconnect (ErrorIsEXIT) is ignored (ErrorReset). Read more from the: /example/atl/Filter4.atl
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) |
MqContextC::LinkCreate $ctx ?args:MkBufferListC...=NULL?
top make ctx to a parent-context and setup a new client-server-link … → API: atlmqmsgque_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...=NULL?
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) |
MqContextC::LinkCreateChild $ctx parent:MqContextC ?args:MkBufferListC...=NULL?
top make a context to a child-context on-top of an existing parent-client-server-link … → API: atlmqmsgque_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) |
MqContextC::LinkDelete $ctx
top close the client-server-link … → API: atlmqmsgque_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 [MqContextC::LinkGetCtxId $ctx]
top get an identifier which is unique per parent-or-child-context … → API: atlmqmsgque_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 [MqContextC::LinkGetParent $ctx]
top get the initial parent-context from a client/server link … → API: atlmqmsgque_MqContextC_LinkGetParent
[in] | ctx | the MqContextS instance to work on |
"MK_NULL"
if ctx is "MK_NULL"
string [MqContextC::LinkGetTargetIdent $ctx]
top get the ident of the link-target … → API: atlmqmsgque_MqContextC_LinkGetTargetIdent
This function is only useful if the link is up and running.
[in] | ctx | the MqContextS instance to work on |
"MK_NULL"
if not connected bool [MqContextC::LinkIsConnected $ctx]
top is the context connected? … → API: atlmqmsgque_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 |
true
or false
bool [MqContextC::LinkIsParent $ctx]
top is the context a parent-context? … → API: atlmqmsgque_MqContextC_LinkIsParent
A context is a parent-context if it was created with MqLinkCreate
[in] | ctx | the MqContextS instance to work on |
true
or false
MqContextC::LinkShutdown $ctx
top shutdown the communication with a server → API: atlmqmsgque_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_Log_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 MkRuntimeLogTargetSet 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="MK_NULL" → use default-format) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
MqContextC::Log $ctx ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?
top log the MqContextC … → API: atlmkkernel_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="MK_NULL" → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
MqContextC::LogConfig $ctx ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?
top log the MqContextC part MqConfigS … → API: atlmqmsgque_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="MK_NULL" → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
MqContextC::LogEnv $ctx ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?
top log the MqContextC part MqEnvS … → API: atlmqmsgque_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="MK_NULL" → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
MqContextC::LogLink $ctx ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?
top log the MqContextC part MqLinkS … → API: atlmqmsgque_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="MK_NULL" → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
MqContextC::LogSetup $ctx ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?
top log the MqContextC part MqSetupS … → API: atlmqmsgque_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="MK_NULL" → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
MqContextC::LogShort $ctx ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0? ?label:string="NULL"?
top log the MqContextC with less info then MqContextLog … → API: atlmqmsgque_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="MK_NULL" → 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, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
MqContextC::LogType $ctx ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?
top log the MqContextC part MkTypeS … → API: atlmqmsgque_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="MK_NULL" → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
string [MqContextC::LogParentOrChild $ctx]
top is ctx a PARENT or a CHILD ? … → API: atlmqmsgque_MqContextC_LogParentOrChild
[in] | ctx | the MqContextS instance to work on |
string [MqContextC::LogServerOrClient $ctx]
top is ctx a SERVER or a CLIENT ? … → API: atlmqmsgque_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_Misc_C_API - MqContextC - various functions to work on a context …
MkBufferC [MqContextC::GetBuffer $ctx]
top get the MqContextS::ctxbuf object → API: atlmqmsgque_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"MK_NULL"
for a non-error result. string [MqContextC::ToString $ctx]
top String-Slot - returns the string representation of the inst … → API: atlmkkernel_MkObjectC_ToString
The string is a human-readable form of the data stored in the object.
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 "MK_NULL"
for a non-error result. int32 [MqContextC::Exit $ctx ?callfunc:string="MK_NULL"? ?callfile:string="MK_NULL"? ?callline:int32=-1?]
top delete the context and exit the current process or thread … → API: atlmqmsgque_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, "MK_NULL" = resolve-own-name) |
[in] | callfile | the name of the file the call take place (e.g. FILE) |
[in] | callline | the number of the line the call take place (e.g. LINE) |
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 atlmqmsgque, does exit but the process continue to work. To make it short use MqExit to exit your application.
The following steps are performed:
MK_NO_RETURN
besause the MqExit can be an overloaded with:
MqContextC [MqContextC::GetRoot $ctx]
top get the Root (toplevel initial context) → API: atlmqmsgque_MqContextC_GetRoot
MqContextC::ProcessEvent $ctx ?wait:MqWaitOnEventE=NO? ?timeout:MkTimeoutE|int32=DEFAULT?
top enter the event-loop and wait for an incoming service-request. … → API: atlmqmsgque_MqContextC_ProcessEvent
This function is used to enter the event-loop and start listen on open file-handles and to call MqEventIF 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_Proxy_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
MqContextC::ProxyForward $sourceCtx targetCtx:MqContextC ?dump:MqDumpC=NULL? ?timeout:MkTimeoutE|int32=DEFAULT?
top send the entire read-data-package-data to the link-target … → API: atlmqmsgque_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 "MK_NULL" , 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) |
MqContextC::ProxyItem $sourceCtx targetCtx:MqContextC
top Copy a single-data-item from the sourceCtx to the targetCtx. → API: atlmqmsgque_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.atl
→ read-safety: Make a nested service-call
proc Ot_CSV1 { myNs } { # read the input-data from the CSV1-service-call # client → server set inI [ReadI32 $myNs] incr inI # call the CSV2-service at the client, wait 10sec for timeout # server → client → server set retI [Send $myNs "Wt" 10 "CSV2:I@I" $inI] incr retI # answer the CSV1-service-call with the result from the CSV2-service-call # server → client Send $myNs "R" "I" $retI }
C-API: MqContextC_ReadApi_Atom_C_API - MqContextC - read a single-data-item outof a read-data-package …
MkBufferListC [MqContextC::ReadALL $ctx ?val_inout:MkBufferListC=NULL?]
top get a temporary MkBufferListC from all data in the read-data-package … → API: atlmqmsgque_MqContextC_ReadALL
[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] | val_inout | the reference object or "MK_NULL" at error |
"MK_NULL"
."MK_NULL"
object than the reference object is populated with the result."MK_NULL"
object than :"MK_NULL"
for a non-error result.MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
"MK_NULL"
for a non-error result. MkBufferListC [MqContextC::ReadBFL $ctx]
top get a temporary MkBufferListC from next list-item in the read-data-package … → API: atlmqmsgque_MqContextC_ReadBFL
If the next item in the read-data-package is a list-item, (created with MqReadL_START and MqContextC::ReadL_END $ctx
), 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) |
"MK_NULL"
for a non-error result. binary [MqContextC::ReadBinaryR $ctx]
top read a MkBinaryR from the read-data-package … → API: atlmqmsgque_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 [MqContextC::ReadBUF $ctx]
top get a temporary MkBufferC from the read-data-package … → API: atlmqmsgque_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 atlmqmsgque and must not be freed.
Example from server.atl
→ read and update a MkBufferC
# START - ReadBUF - Example, read a buffer-object and append a string set buf [ReadBUF $myNs] MkBufferC::AppendC $buf "- a really log text to overwrite the already allocated space" SendBUF $myNs $buf set i [ReadI32 $myNs] SendI32 $myNs [expr {$i+1}] myooX::DestroyN $buf
[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 "MK_NULL" , 2. If there is an error, the out-value remains unchanged. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
"MK_NULL"
"MK_NULL"
for a non-error result. MK_HDL [MqContextC::ReadHDL $ctx]
top read the handle from the read-data-package → API: atlmqmsgque_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...] [MqContextC::ReadLIST $ctx]
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 [MqContextC::ReadLONG $ctx]
top read the long native object from the read-data-package → API: atlmqmsgque_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 [MqContextC::ReadNEXT $ctx]
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 [MqContextC::ReadStringR $ctx]
top read a MkStringR from the read-data-package … → API: atlmqmsgque_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) |
[MqContextC::ReadTT $ctx]
The ReadTT provide a single function for every PRIMITIVE TYPE
attribute | return | command | C-API : |
---|---|---|---|
int8 | [MqContextC::ReadI8 $ctx] | MqReadI8_RT | |
int16 | [MqContextC::ReadI16 $ctx] | MqReadI16_RT | |
int32 | [MqContextC::ReadI32 $ctx] | MqReadI32_RT | |
int64 | [MqContextC::ReadI64 $ctx] | MqReadI64_RT | |
string | [MqContextC::ReadSTR $ctx] | MqReadSTR_RT | |
binary | [MqContextC::ReadBIN $ctx] | MqReadBIN_RT | |
bool | [MqContextC::ReadBOL $ctx] | MqReadBOL_RT | |
float | [MqContextC::ReadFLT $ctx] | MqReadFLT_RT | |
double | [MqContextC::ReadDBL $ctx] |
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 …
MqContextC::ReadL_END $ctx
top finish to extract a list-items from the read-data-package. … → API: atlmqmsgque_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) |
MqContextC::ReadL_START $ctx ?buf:MkBufferC=NULL?
top start to extract a list-items from the read-data-package. … → API: atlmqmsgque_MqContextC_ReadL_START
Initialize the read with the current body-item or an optional MkBufferC. This command requires a final MqContextC::ReadL_END $ctx
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 "MK_NULL" to use the next item from the read-data-package. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqContextC::ReadT_END $ctx
top finish to extract a longterm-transaction-item from the read-data-package. … → API: atlmqmsgque_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) |
MqContextC::ReadT_START $ctx
top start to extract a longterm-transaction-item from the read-data-package. … → API: atlmqmsgque_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 MqContextC::ReadL_END $ctx
to finish the read.
Example from server.atl
→ read the results from a service-call with transaction-support
proc Ot_TRN2 { myNs } { namespace upvar $myNs my(i) i my(j) j ReadT_START $myNs set i [ReadI32 $myNs] ReadT_END $myNs set j [ReadI32 $myNs] }
[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 [MqContextC::ReadGetNextType $ctx]
top get the type (MkTypeE) of the next Item in the read-data-buffer or "0" if not available → API: atlmqmsgque_MqContextC_ReadGetNextType
[in] | ctx | the MqContextS instance to work on |
int32 [MqContextC::ReadGetNumItems $ctx]
top get the number of items left in the read-data-package … → API: atlmqmsgque_MqContextC_ReadGetNumItems
[in] | ctx | the MqContextS instance to work on |
bool [MqContextC::ReadItemExists $ctx]
top check if an item exists in the read-data-package … → API: atlmqmsgque_MqContextC_ReadItemExists
[in] | ctx | the MqContextS instance to work on |
true
or false
MqContextC::ReadUndo $ctx
top undo the last MqContextC READ API function call … → API: atlmqmsgque_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_Route_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:
MqContextC::RouteCreate $ctx 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.atl
→ create a new loop-server package require lib_85 package require atlmqmsgque ::myooX::ClassN ::MyLoopServer { SuperI ::MqContextC # factory startup proc MyLoopServer {myNs {tmpl ""}} { namespace upvar $myNs my(mydata) mydata; MqContextC $myNs $tmpl ConfigSetServerSetup $myNs ServerSetup # set the "mydata" attribute to the master-context set mydata "Hello World"; } # service to serve all EXTERNAL requests for token "HLWO" proc HLWO_srv { myNs } { # get the "loopback" context set loop [SlaveGet $myNs LOOPBACK] # call the LOOP service on the SAME server MqContextC::Send $loop "W" "LOOP" # answer HLWO with string-return from LOOP Send $myNs "R" "C" [MqContextC::ReadSTR $loop] } # service to serve all INTERNAL requests for token "LOOP" proc LOOP_srv { myNs } { # get the "master" context set master [SlaveGetMaster $myNs] # answer LOOP with data from MASTER->mydata attribute namespace upvar $master my(mydata) mydata; Send $myNs "R" "C" $mydata } # setup a server-context - called for every new server-context proc ServerSetup { myNs } { # EXTERNAL: link the "HLWO" service with "HLWO_srv" ServiceCreate $myNs "HLWO" HLWO_srv # INTERNAL: link the "LOOP" service with "LOOP_srv" ServiceCreate [SlaveGet $myNs MQ_SLAVE_LOOPBACK] "LOOP" LOOP_srv } } MqMsgque::Main { # create "MyLoopServer" factory... and the instance set srv [MqFactoryC::New [MqFactoryC::Add ::MyLoopServer]] try { MqContextC::LinkCreate $srv $argv MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
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....
MqContextC::RouteCreate $ctx route:string service:string ?overwrite:bool=false?
top create/delete a routing-link between context an a service using route → API: atlmqmsgque_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) |
MqContextC::RouteDelete $ctx route:string service:string ?overwrite:bool=false?
top delete a routing-link created with MqRouteCreate → API: atlmqmsgque_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 [MqContextC::RouteGetPath $ctx]
top return the absolut route-connection-string up to the current ctx … → API: atlmqmsgque_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 "MK_NULL" on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MkBufferListC [MqContextC::RouteGetTree $ctx]
top create an overview about all available routing-target and services … → API: atlmqmsgque_MqContextC_RouteGetTree
The data returned is a list of "ROUTE|IDENT|SERVICE,..."
string items.
ROUTE
is the route-connection-string used in MqContextC::RouteCreate $ctx 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.atl
→ 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...] [MqContextC::RouteResolve $ctx ident:string ?retnum:int32=-1?]
top return a list of all context belonging to ident … → API: atlmqmsgque_MqContextC_RouteResolve
This api-proc is used to return all context with MqLinkS::targetIdent == ident
.
In addition the following special ident are recognized:
"MK_NULL"
or DOT=. or ClassIdentGet -> The loopback-slave Example from server.atl
→ in a service call return all connected targets
foreach myctx [RouteResolve $myNs [ReadSTR $myNs]] { SendSTR $myNs [LinkGetTargetIdent $myctx] }
"MK_NULL"
for a non-error result."MK_NULL"
.[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. |
"MK_NULL"
. MqContextC::RouteTraverse $ctx service:string ?args:MkBufferListC...=NULL?
top traverse a tree down and call service if available. → API: atlmqmsgque_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) |
MqContextC::SendBFL $ctx val:MkBufferListC
top append a MkBufferListC object to the send-data-package object … → API: atlmqmsgque_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) |
MqContextC::SendBinaryR $ctx val:binary
top append a MkBinaryR object to the send-data-package. … → API: atlmqmsgque_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. MqContextC::SendBUF $ctx val:MkBufferC
top append a MkBufferC object to the send-data-package object … → API: atlmqmsgque_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) |
MqContextC::SendBUS_FLAT $ctx val:MkBufferStreamC
top append a MkBufferStreamC object to the send-data-package object … → API: atlmqmsgque_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) |
MqContextC::SendHDL $ctx val:MK_HDL
top send the handle to the send-data-package → API: atlmqmsgque_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) |
MqContextC::SendL_FLAT $ctx val:MkBufferListC
top append a MkBufferListC object as flat list of items to the send-data-package object … → API: atlmqmsgque_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) |
MqContextC::SendLONG $ctx val:long
top send the long native object to the send-data-package → API: atlmqmsgque_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) |
MqContextC::SendStringR $ctx val:string
top MqContextC - append a native PRIMITIVE TYPE value to the send-data-package … → API: atlmqmsgque_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.MqContextC::SendTT $ctx val:int8
The SendTT provide a single function for every PRIMITIVE TYPE
attribute | return | command | C-API : |
---|---|---|---|
MqContextC::SendI8 $ctx val:int8 | MqSendI8_RT | ||
MqContextC::SendI16 $ctx val:int16 | MqSendI16_RT | ||
MqContextC::SendI32 $ctx val:int32 | MqSendI32_RT | ||
MqContextC::SendI64 $ctx val:int64 | MqSendI64_RT | ||
MqContextC::SendSTR $ctx val:string | MqSendSTR_RT | ||
MqContextC::SendBIN $ctx val:binary | MqSendBIN_RT | ||
MqContextC::SendBOL $ctx val:bool | MqSendBOL_RT | ||
MqContextC::SendFLT $ctx val:float | MqSendFLT_RT | ||
MqContextC::SendDBL $ctx 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) |
MqContextC::SendEND $ctx token:string[4] ?timeout:MkTimeoutE|int32=DEFAULT?
top MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service … → API: atlmqmsgque_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) |
MqContextC::SendEND_AND_CALLBACK $ctx 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: atlmqmsgque_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 MqContextC::SendEND_AND_SUB $ctx 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: atlmqmsgque_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 MqContextC::SendRETURN_SUB $ctx
. At the end ONE final and EMPTY MqContextC::SendRETURN $ctx
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) |
MqContextC::SendRETURN $ctx
) 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 MqContextC::SendEND_AND_TRANSACTION $ctx 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: atlmqmsgque_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 MqServerSetupIF) 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 MqEventIF 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.atl
→ make a logterm-transaction-call using the LOW and the HIGH api
package require lib_85 package require atlmqmsgque namespace import MqContextC::* proc callback {ctx} { ReadT_START $ctx set myPrivateHandle [ReadSTR $ctx] ReadT_END $ctx set myServiceResult [ReadI32 $ctx] puts "myPrivateHandle=$myPrivateHandle, myServiceResult=$myServiceResult" } # setup the client-context set ctx [myooX::NewN ::MqContextC] try { ConfigSetName $ctx "MyTransaction" # setup commandline arguments used for parsing set args [MkBufferListC::CreateLA {*}$argv] # check if the '--token' option is available, default "SRVC" set token [MkBufferListC::CheckOptionSTR $args "--token" "SRVC"] # connect to the server LinkCreate $ctx $args # register callback ServiceCreate $ctx CLB1 callback # send block using the LOW-Api SendSTART $ctx SendT_START $ctx SendSTR $ctx "Privat_Data_1" SendT_END $ctx SendI32 $ctx 11111 SendEND_AND_TRANSACTION $ctx $token CLB1 # send block using the HIGN-Api -> same as above, but shorter Send $ctx "T" CLB1 "$token:(C)I" "Privat_Data_2" 22222 # now we wait for exact ONE result of the $ctx ProcessEvent $ctx MQ_WAIT_OWN } on error {} { ErrorCatch $ctx } finally { Exit $ctx }
MqContextC::SendEND_AND_WAIT $ctx token:string[4] ?timeout:MkTimeoutE|int32=DEFAULT?
top finish the send-data-block, call the remote service and wait for result… → API: atlmqmsgque_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 MqEventIF 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) |
MqContextC::SendSTART $ctx
top initialize the send-data-package. … → API: atlmqmsgque_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) |
MqContextC::SendSYNC $ctx
top garantee that all pending asynchronous-service-calls are processed. … → API: atlmqmsgque_MqContextC_SendSYNC
The asynchronous-service-call is defined at: MqContextC_ServiceApi_Service_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) |
MqContextC::SendL_END $ctx
top finish to append an embedded body-list-item to the send-data-package. … → API: atlmqmsgque_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) |
MqContextC::SendL_START $ctx
top start to append an embedded body-list-item to the send-data-package. … → API: atlmqmsgque_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) |
MqContextC::SendT_END $ctx
top closed a longterm-transaction-item … → API: atlmqmsgque_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) |
MqContextC::SendT_START $ctx
top open a longterm-transaction-item … → API: atlmqmsgque_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.atl
→ make a service-call with transaction-support
proc Ot_TRNS { myNs } { namespace upvar $myNs my(i) i my(j) j Send $myNs "T" TRN2 "ECOI:(I)I" 9876 [ReadI32 $myNs] ProcessEvent $myNs MQ_WAIT_ONCE Send $myNs "R" "II" $i $j }
[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) |
MqContextC::SendERROR $ctx
top send the data from the MkErrorC to the link target . … → API: atlmqmsgque_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) |
MqContextC::SendRETURN $ctx
top MqContextC - finish the send-data-block on the server and optional return the results. … → API: atlmqmsgque_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) |
MqContextC::SendRETURN_SUB $ctx
top return Sub-Data-Blocks required by MqSendEND_AND_SUB … → API: atlmqmsgque_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 MqContextC::SendRETURN $ctx
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_Service_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 MqServerSetupIF method and finally cleanup with MqServerCleanupIF.
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.atl
→ define the service HLWO on the server-link-setup
package require lib_85 package require atlmqmsgque # package-item ::myooX::ClassN ::MyServer { SuperI ::MqContextC # service to serve all incoming requests for token "HLWO" proc myFirstService {myNs} { SendSTART $myNs SendSTR $myNs "[ReadSTR $myNs] World" SendRETURN $myNs } # define a service as link between the token "HLWO" and the callback "MyFirstService" proc serverSetup {myNs} { ServiceCreate $myNs "HLWO" myFirstService } # factory startup (constructor) proc MyServer {myNs {tmpl ""}} { MqContextC $myNs $tmpl ConfigSetServerSetup $myNs serverSetup } } # package-main MqMsgque::Main { # setup commandline arguments for later use set args [MkBufferListC::CreateLA {*}$argv] # create "MyServer" factory... and make it to the default. set fct [MqFactoryC::Default [MqFactoryC::Add ::MyServer]] # inspect commandline-argument for the "factory" to choose... and create a object set fct [MqFactoryC::GetCalledL $args] set srv [MqFactoryC::New $fct] try { MqContextC::LinkCreate $srv $args MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
MqContextC::ServiceCreate $ctx token:string[4] callback:callable
top create a link between a service-token and a service-callback … → API: atlmqmsgque_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] [MqContextC::ServiceTokenGet $ctx]
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.atl
→ setup the services for server and filter
proc FilterSetup { myNs } { set ftr [SlaveGetFilter $myNs] namespace upvar $myNs FH FH set FH "" ServiceCreate $myNs "LOGF" LOGF ServiceCreate $myNs "EXIT" EXIT ServiceCreate $myNs "SOEX" SOEX ServiceCreate $myNs "ERR1" ERR1 ServiceStorage $myNs "PRNT" ServiceStorage $myNs "PRN2" ServiceCreate $myNs "+ALL" FilterIn MqContextC::ServiceCreate $ftr "WRIT" WRIT ServiceCreate $myNs "WRIT" WRIT MqContextC::ServiceProxy $ftr "WRT2" MASTER }
[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 MqContextC::ServiceDelete $ctx token:string[4]
top delete a service. … → API: atlmqmsgque_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 [MqContextC::ServiceIsTransaction $ctx]
top check if the ongoing-service-call belongs to a transaction … → API: atlmqmsgque_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 |
true
or false
MqContextC::ServiceProxy $ctx token:string[4] ?id:MqSlaveE|int32=MQ_SLAVE_OTHER?
top create a service to link a master-context with a slave-context. … → API: atlmqmsgque_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) |
MqContextC::ServiceProxyCtx $ctx token:string[4] target:MqContextC
top same as MqServiceProxy but use an MqContextC as input. → API: atlmqmsgque_MqContextC_ServiceProxyCtx
bool [MqContextC::ServiceProxyCtxExists $ctx token:string[4] target:MqContextC]
top check if service who belongs to token is a proxy-service → API: atlmqmsgque_MqContextC_ServiceProxyCtxExists
This is used for route (MqRouteDelete) to identify the service-usage
MqContextC::ServiceProxyRoundRobin $ctx token:string[4] ident:string
top create a proxy-service using Round-Robin as load-balancer … → API: atlmqmsgque_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) |
MqContextC::ServiceStorage $ctx token:string[4]
top setup a service listen on a MqContextC_ServiceApi_Identifer and save all read-data-package into the STORAGE … → API: atlmqmsgque_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.atl
→ using MqServiceStorage to store all packages from service PRNT
and PRN2
into database
proc FilterSetup { myNs } { set ftr [SlaveGetFilter $myNs] namespace upvar $myNs FH FH set FH "" ServiceCreate $myNs "LOGF" LOGF ServiceCreate $myNs "EXIT" EXIT ServiceCreate $myNs "SOEX" SOEX ServiceCreate $myNs "ERR1" ERR1 ServiceStorage $myNs "PRNT" ServiceStorage $myNs "PRN2" ServiceCreate $myNs "+ALL" FilterIn MqContextC::ServiceCreate $ftr "WRIT" WRIT ServiceCreate $myNs "WRIT" WRIT MqContextC::ServiceProxy $ftr "WRT2" MASTER }
[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 [MqContextC::ServiceTokenCheck $ctx token:string[4]]
top in an ongoing-service-call check if the current MqContextC_ServiceApi_Identifer is token … → API: atlmqmsgque_MqContextC_ServiceTokenCheck
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
true
or false
bool [MqContextC::ServiceTokenExists $ctx token:string[4]]
top check if the MqContextC_ServiceApi_Identifer token is defined as ctx service … → API: atlmqmsgque_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 |
true
or false
string[4] [MqContextC::ServiceTokenGet $ctx]
top in an ongoing-service-call get the current MqContextC_ServiceApi_Identifer … → API: atlmqmsgque_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_Slave_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.atl
→ create a new loop-server package require lib_85 package require atlmqmsgque ::myooX::ClassN ::MyLoopServer { SuperI ::MqContextC # factory startup proc MyLoopServer {myNs {tmpl ""}} { namespace upvar $myNs my(mydata) mydata; MqContextC $myNs $tmpl ConfigSetServerSetup $myNs ServerSetup # set the "mydata" attribute to the master-context set mydata "Hello World"; } # service to serve all EXTERNAL requests for token "HLWO" proc HLWO_srv { myNs } { # get the "loopback" context set loop [SlaveGet $myNs LOOPBACK] # call the LOOP service on the SAME server MqContextC::Send $loop "W" "LOOP" # answer HLWO with string-return from LOOP Send $myNs "R" "C" [MqContextC::ReadSTR $loop] } # service to serve all INTERNAL requests for token "LOOP" proc LOOP_srv { myNs } { # get the "master" context set master [SlaveGetMaster $myNs] # answer LOOP with data from MASTER->mydata attribute namespace upvar $master my(mydata) mydata; Send $myNs "R" "C" $mydata } # setup a server-context - called for every new server-context proc ServerSetup { myNs } { # EXTERNAL: link the "HLWO" service with "HLWO_srv" ServiceCreate $myNs "HLWO" HLWO_srv # INTERNAL: link the "LOOP" service with "LOOP_srv" ServiceCreate [SlaveGet $myNs MQ_SLAVE_LOOPBACK] "LOOP" LOOP_srv } } MqMsgque::Main { # create "MyLoopServer" factory... and the instance set srv [MqFactoryC::New [MqFactoryC::Add ::MyLoopServer]] try { MqContextC::LinkCreate $srv $argv MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
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 [MqContextC::SlaveCheck $ctx id:MqSlaveE|int32]
top check if slave-id is valid → API: atlmqmsgque_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 MqContextC::SlaveCreate $ctx id:MqSlaveE|int32 slave:MqContextC
top create a master/slave link between the master-parent-context and the slave-parent-context … → API: atlmqmsgque_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.atl
→ without reflection-support ... the factory is required :
Example from server.atl
→ the factory is created at startup :
With reflection-support ... just the instance-constructor is required to create an instance:
[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) |
MqContextC::SlaveDelete $ctx id:MqSlaveE|int32
top Delete a slave object from a master/slave link identified by id. … → API: atlmqmsgque_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 [MqContextC::SlaveGet $ctx id:MqSlaveE|int32]
top get the slave-context from a master-context … → API: atlmqmsgque_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 "MK_NULL" on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqContextC [MqContextC::SlaveGetFilter $ctx]
top get the filter-ctx or the master-ctx … → API: atlmqmsgque_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 "MK_NULL" on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqContextC [MqContextC::SlaveGetMaster $ctx]
top opposite function of MqSlaveGetFilter → API: atlmqmsgque_MqContextC_SlaveGetMaster
"MK_NULL"
is returned MqContextC [MqContextC::SlaveGetProxy $ctx id:MqSlaveE|int32]
top on slave return the master and on master return the slave identified by id. → API: atlmqmsgque_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 "MK_NULL" on error |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
bool [MqContextC::SlaveIs $ctx]
top is the context a slave-context ? … → API: atlmqmsgque_MqContextC_SlaveIs
[in] | ctx | the MqContextS instance to work on |
true
or false
MqContextC::SlaveWorker $ctx id:MqSlaveE|int32 ?fct:string="WORKER"? ?args:MkBufferListC...=NULL?
top create a master/slave link using the image of the ctx object self. … → API: atlmqmsgque_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.atl
→ 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 "MK_NULL" or '\0' or "WORKER" . if ident is "MK_NULL" 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_Storage_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 |
MqContextC::StorageClose $ctx
top close the storage. … → API: atlmqmsgque_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 [MqContextC::StorageCount $ctx]
top count the number of storage-rows … → API: atlmqmsgque_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) |
MqContextC::StorageDecrRef $ctx transLId:int32
top decrease the internal refCount lock of the database-entry → API: atlmqmsgque_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 [MqContextC::StorageDelete $ctx ?*transLIdP_inout:int32=0?]
top delete the storage-row identified by the transLIdP_inout … → API: atlmqmsgque_MqContextC_StorageDelete
The transLIdP_inout is the value returned by a previous MqStorageImport. If transLIdP_inout is "MK_NULL"
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 [MqContextC::StorageErrCnt $ctx transLId:int32]
top increment and return the database row-error-count for the row defined with transLId → API: atlmqmsgque_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 [MqContextC::StorageExport $ctx]
top export the read-data-package into the STORAGE … → API: atlmqmsgque_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 [MqContextC::StorageImport $ctx ?*transLIdP_inout:int32=0?]
top import the storage-package into the read-data-package … → API: atlmqmsgque_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 "MK_NULL" 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. MqContextC::StorageIncrRef $ctx transLId:int32
top increase the internal refCount lock of the database-entry → API: atlmqmsgque_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) |
MqContextC::StorageLog $ctx ?callfunc:string="MK_NULL"?
top log the storage the status of the open transactions → API: atlmqmsgque_MqContextC_StorageLog
MqContextC::StorageOpen $ctx storageFile:string
top switch to a file-based-transaction-database … → API: atlmqmsgque_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} [MqContextC::StorageResolve $ctx]
top extract the context->link.protect.rmtTransLId
entry from the database → API: atlmqmsgque_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 |
atlmqmsgque is using a class-attribute as instance-storage. …
variable
keyword: 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 | ||
CTOR | create a MqDumpC as export of the ctx-read-data-package … | ||
Error | export the context->error into the dump-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 atlmqmsgque 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 "MK_NULL" 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 "MK_NULL"
if invalid… → API: atlmqmsgque_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_NULL"
if netHdl is invalid MK_HDL [MqDumpC::HandleGet $dmp]
top Handle-Get-Slot - returns a export-hdl to the MqDumpC useable for external storage → API: atlmkkernel_MkObjectC_HandleGet
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MqDumpHandleResolve.
By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
[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: atlmqmsgque_MqDumpC_Instances
The head-instance is the last instance created.
MqDumpC [MqDumpC::Next $dmp]
top get next instance from linked-list of MqDumpS type → API: atlmqmsgque_MqDumpC_Next
MqDumpC [MqDumpC::Prev $dmp]
top get previous instance from linked-list of MqDumpS type → API: atlmqmsgque_MqDumpC_Prev
MqDumpC - Misc class functions …
(static) MqDumpC [MqDumpC::GetNull]
top Null-Slot - return a MqDumpC typed NULL
instance … → API: atlmqmsgque_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=NULL?]
top create a MqDumpC as export of the ctx-read-data-package … → API: atlmqmsgque_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 | the reference object or "MK_NULL" at error |
"MK_NULL"
."MK_NULL"
object than the reference object is populated with the result."MK_NULL"
object than :"MK_NULL"
for a non-error result.MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
"MK_NULL"
or a result of a previous MqDumpExport or MqDumpError."MK_NULL"
or garbage … new memory will be allocated… If the dump memory will NOT be reused… free the memory with (6.)(constructor,static) MqDumpC [MqDumpC::BinSet data:binary]
top create an MqDumpS
object from binary data → API: atlmqmsgque_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::CTOR ctx:MqContextC ?dumpP_inout:MqDumpC=NULL?]
top create a MqDumpC as export of the ctx-read-data-package … → API: atlmqmsgque_MqDumpC_CTOR
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 | the reference object or "MK_NULL" at error |
"MK_NULL"
."MK_NULL"
object than the reference object is populated with the result."MK_NULL"
object than :"MK_NULL"
for a non-error result.MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
"MK_NULL"
or a result of a previous MqDumpExport or MqDumpError."MK_NULL"
or garbage … new memory will be allocated… If the dump memory will NOT be reused… free the memory with (6.)(constructor,static) MqDumpC [MqDumpC::Error error:MqContextC ?dumpP_inout:MqDumpC=NULL?]
top export the context->error into the dump-package … → API: atlmqmsgque_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 reference object or "MK_NULL" at error |
"MK_NULL"
."MK_NULL"
object than the reference object is populated with the result."MK_NULL"
object than :"MK_NULL"
for a non-error result.MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
(destructor) MqDumpC::Delete $dmp
top Destructor - delete a MqDumpC instance … → API: MqDumpDelete_RT
binary [MqDumpC::BinGet $dump]
top export the binary data from an MqDumpS
object → API: atlmqmsgque_MqDumpC_BinGet
[in] | dump | the source object |
MqDumpS
object… do NOT free. MqDumpC::Import $dump ctx:MqContextC
top import the dump-package into the ctx-read-data-package … → API: atlmqmsgque_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) |
"MK_NULL"
for a non-error result.C-API: MqDumpC_Misc_C_API - MqDumpC - various functions to work on a dump …
MqDumpC::Log $dmp ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?
top log the MqDumpC … → API: atlmkkernel_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="MK_NULL" → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
long [MqDumpC::SizeGet $dump]
top report the binary data size from an MqDumpS
object → API: atlmqmsgque_MqDumpC_SizeGet
[in] | dump | the source object |
string [MqDumpC::TokenGet $dump]
top return the MqContextC_ServiceApi_Identifer … → API: atlmqmsgque_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 … | ||
CTOR | 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 atlmqmsgque. 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 "MK_NULL" 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 "MK_NULL"
if invalid… → API: atlmqmsgque_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_NULL"
if netHdl is invalid MK_HDL [MqFactoryC::HandleGet $fct]
top Handle-Get-Slot - returns a export-hdl to the MqFactoryC useable for external storage → API: atlmkkernel_MkObjectC_HandleGet
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the MqFactoryHandleResolve.
By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
[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: atlmqmsgque_MqFactoryC_Instances
The head-instance is the last instance created.
MqFactoryC [MqFactoryC::Next $fct]
top get next instance from linked-list of MqFactoryS type → API: atlmqmsgque_MqFactoryC_Next
MqFactoryC [MqFactoryC::Prev $fct]
top get previous instance from linked-list of MqFactoryS type → API: atlmqmsgque_MqFactoryC_Prev
MqFactoryC - Misc class functions …
(static) MqFactoryC [MqFactoryC::GetNull]
top Null-Slot - return a MqFactoryC typed NULL
instance … → API: atlmqmsgque_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: atlmqmsgque_MqFactoryC_Add
The factory is required to get all atlmqmsgque features.
The context is a instance from a subclass of MqContextC …
The constructor require a tmpl argument with default "MK_NULL"
Example from example_code.atl
→ setup a server called MyServer
with one service MYTO
myooX::ClassN ::MyServer { SuperI ::MqContextC ... proc MyServer {myNs {tmpl ""}} { MqContextC $myNs $tmpl ConfigSetServerSetup $myNs serverSetup ... } proc $myNs serverSetup {} { ServiceCreate $myNs "MYTO" myService ... } ... } # package-main MqMsgque::Main { ... # create "MyServer" factory... and make it to the default. set fct [MqFactoryC::Default [MqFactoryC::Add ::MyServer]] ... }
Example from Filter5.atl
→ create a new context using factory F1; F2 or F3 read from the commandline
MqMsgque::Main { # create buffer-list of the application arguments set largs [MkBufferListC::CreateLA {*}$argv] # add factories MqFactoryC::Add ::F1 MqFactoryC::Add ::F2 MqFactoryC::Add ::F3 # call factory using the !first! application argument set srv [MqFactoryC::New [MqFactoryC::GetCalledL $largs]] try { # configure and start the server MqContextC::LinkCreate $srv $largs # start event-loop and wait forever MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { # set the libmqmsgque error from the tcl error MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
[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 "MK_NULL" 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 |
"MK_NULL"
on error(constructor,static) MqFactoryC [MqFactoryC::CTOR constructor:class ?ident:string="MK_NULL"?]
top Add a new MqFactoryC identified by factory-identifier and defined by factory-constructor … → API: atlmqmsgque_MqFactoryC_CTOR
The factory is required to get all atlmqmsgque features.
The context is a instance from a subclass of MqContextC …
The constructor require a tmpl argument with default "MK_NULL"
Example from example_code.atl
→ setup a server called MyServer
with one service MYTO
myooX::ClassN ::MyServer { SuperI ::MqContextC ... proc MyServer {myNs {tmpl ""}} { MqContextC $myNs $tmpl ConfigSetServerSetup $myNs serverSetup ... } proc $myNs serverSetup {} { ServiceCreate $myNs "MYTO" myService ... } ... } # package-main MqMsgque::Main { ... # create "MyServer" factory... and make it to the default. set fct [MqFactoryC::Default [MqFactoryC::Add ::MyServer]] ... }
Example from Filter5.atl
→ create a new context using factory F1; F2 or F3 read from the commandline
MqMsgque::Main { # create buffer-list of the application arguments set largs [MkBufferListC::CreateLA {*}$argv] # add factories MqFactoryC::Add ::F1 MqFactoryC::Add ::F2 MqFactoryC::Add ::F3 # call factory using the !first! application argument set srv [MqFactoryC::New [MqFactoryC::GetCalledL $largs]] try { # configure and start the server MqContextC::LinkCreate $srv $largs # start event-loop and wait forever MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { # set the libmqmsgque error from the tcl error MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
[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 "MK_NULL" 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 |
"MK_NULL"
on error(destructor) MqFactoryC::Delete $fct
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 [MqFactoryC::Dup2 $fct ident:string]
top create a duplicate of the singleton object MqFactoryC using a new factory-identifer → API: atlmqmsgque_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: atlmqmsgque_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] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ident | the factory-identifier to search for |
"MK_NULL"
if ident was not found (static) MqFactoryC [MqFactoryC::GetCalled ?ident:string=""?]
top returns the MqFactoryC identified by ident … → API: atlmqmsgque_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] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | ident | the factory-identifier or "" for the default MqFactoryC |
"MK_NULL"
if nothing was found (static) MqFactoryC [MqFactoryC::GetCalledL largs:MkBufferListC]
top returns the MqFactoryC identified as first argument in the largs MkBufferListC … → API: atlmqmsgque_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 |
"MK_NULL"
if nothing was found string [MqFactoryC::GetOriginalIdent $fct]
top helper function to return MqFactoryS::originalIdent → API: atlmqmsgque_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: atlmqmsgque_MqFactoryC_DefaultIdent
(static) string [MqFactoryC::InitialIdent]
top return the factory-identifier of the initial MqFactoryC → API: atlmqmsgque_MqFactoryC_InitialIdent
(static) MqFactoryC::LogAll ?callfunc:string="MK_NULL"?
top log all "factories" to stderr → API: atlmqmsgque_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, "MK_NULL" = resolve-own-name) |
MqFactoryC [MqFactoryC::Default $fct]
top set the default-attribute to the factory … → API: atlmqmsgque_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] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | fct | the new default MqFactoryC |
Example: from example/atl/server.cs
MqFactoryC [MqFactoryC::Initial $fct]
top set the initial-attribut to fct
… → API: atlmqmsgque_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.atl
→ set Initial attribute to a Factory
MqMsgque::Main { # !!ATTENTION!! if you put the "MqFactoryC::Add" outsite of "MqMsgque::Main" # you get a error like: "...factory identifer already in use..." # because in a "thread" startup... you try to create a factory with SAME NAME again. MqFactoryC::Initial [MqFactoryC::Add ::Filter4 ] set srv [myooX::NewN ::Filter4] try { MqContextC::LinkCreate $srv {*}$argv MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
[in] | mkrt | the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) |
[in] | fct | the new initial MqFactoryC |
MqFactoryC::Log $fct ?fmtobj:MkObjectC=NULL? ?debug:int32=0? ?callfunc:string="MK_NULL"? ?lvl:int32=0?
top log the MqFactoryC … → API: atlmkkernel_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="MK_NULL" → use default-format) |
[in] | debug | the debug level from MkRuntimeS::debug, use 0 <= debug <= 9 (default=0 ) |
[in] | callfunc | a user-defined postfix to identify the calling-function or the environment (default = name-of-function, "MK_NULL" = resolve-own-name) |
[in] | lvl | a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default=0 ) |
MqContextC [MqFactoryC::New $fct]
top create a new MqContextC from a MqFactoryC … → API: atlmqmsgque_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.atl
→ create a new server context
package require lib_85 package require atlmqmsgque # package-item ::myooX::ClassN ::MyServer { SuperI ::MqContextC # service to serve all incoming requests for token "HLWO" proc myFirstService {myNs} { SendSTART $myNs SendSTR $myNs "[ReadSTR $myNs] World" SendRETURN $myNs } # define a service as link between the token "HLWO" and the callback "MyFirstService" proc serverSetup {myNs} { ServiceCreate $myNs "HLWO" myFirstService } # factory startup (constructor) proc MyServer {myNs {tmpl ""}} { MqContextC $myNs $tmpl ConfigSetServerSetup $myNs serverSetup } } # package-main MqMsgque::Main { # setup commandline arguments for later use set args [MkBufferListC::CreateLA {*}$argv] # create "MyServer" factory... and make it to the default. set fct [MqFactoryC::Default [MqFactoryC::Add ::MyServer]] # inspect commandline-argument for the "factory" to choose... and create a object set fct [MqFactoryC::GetCalledL $args] set srv [MqFactoryC::New $fct] try { MqContextC::LinkCreate $srv $args MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
[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 "MK_NULL" on error |
"MK_NULL"
pointer 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 atlmqmsgque 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 atlmqmsgque command pipeline is created with the special character "@" instead of "|" :
msgcmd1 @ msgcmd2 @ msgcmd3
To define a atlmqmsgque 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.atl
→ package require lib_85 package require atlmqmsgque ::myooX::ClassN ::MulServer { SuperI ::MqContextC proc MulServer {myNs {tmpl ""}} { MqContextC $myNs $tmpl ConfigSetServerSetup $myNs ServerSetup } proc MMUL { myNs } { SendSTART $myNs SendDBL $myNs [expr {[ReadDBL $myNs] * [ReadDBL $myNs]}] SendRETURN $myNs } proc ServerSetup { myNs } { ServiceCreate $myNs "MMUL" MMUL } } MqMsgque::Main { set srv [MqFactoryC::New [MqFactoryC::Add ::MulServer "mulserver"]] try { MqContextC::LinkCreate $srv {*}$argv MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
mulclient.atl
→ package require lib_85 package require atlmqmsgque namespace import MqContextC::* myooX::Create2N ::MqContextC ::ctx LinkCreate ::ctx --name "MyMul" {*}$argv SendSTART ::ctx SendDBL ::ctx 3.67 SendDBL ::ctx 22.3 SendEND_AND_WAIT ::ctx "MMUL" puts [ReadDBL ::ctx] Exit ::ctx
MyLoopServer.atl
→ package require lib_85 package require atlmqmsgque ::myooX::ClassN ::MyLoopServer { SuperI ::MqContextC # factory startup proc MyLoopServer {myNs {tmpl ""}} { namespace upvar $myNs my(mydata) mydata; MqContextC $myNs $tmpl ConfigSetServerSetup $myNs ServerSetup # set the "mydata" attribute to the master-context set mydata "Hello World"; } # service to serve all EXTERNAL requests for token "HLWO" proc HLWO_srv { myNs } { # get the "loopback" context set loop [SlaveGet $myNs LOOPBACK] # call the LOOP service on the SAME server MqContextC::Send $loop "W" "LOOP" # answer HLWO with string-return from LOOP Send $myNs "R" "C" [MqContextC::ReadSTR $loop] } # service to serve all INTERNAL requests for token "LOOP" proc LOOP_srv { myNs } { # get the "master" context set master [SlaveGetMaster $myNs] # answer LOOP with data from MASTER->mydata attribute namespace upvar $master my(mydata) mydata; Send $myNs "R" "C" $mydata } # setup a server-context - called for every new server-context proc ServerSetup { myNs } { # EXTERNAL: link the "HLWO" service with "HLWO_srv" ServiceCreate $myNs "HLWO" HLWO_srv # INTERNAL: link the "LOOP" service with "LOOP_srv" ServiceCreate [SlaveGet $myNs MQ_SLAVE_LOOPBACK] "LOOP" LOOP_srv } } MqMsgque::Main { # create "MyLoopServer" factory... and the instance set srv [MqFactoryC::New [MqFactoryC::Add ::MyLoopServer]] try { MqContextC::LinkCreate $srv $argv MqContextC::ProcessEvent $srv MQ_WAIT_FOREVER } on error {} { MqContextC::ErrorCatch $srv } finally { MqContextC::Exit $srv } }
MyClient.atl
→ package require lib_85 package require atlmqmsgque # create a context using the static atlmqmsgque CTOR method "Create" set ctx [MqContextC::Create] try { MqContextC::ConfigSetName $ctx "MyClient" MqContextC::LinkCreate $ctx {*}$argv MqContextC::SendSTART $ctx MqContextC::SendSTR $ctx "Hello" MqContextC::SendEND_AND_WAIT $ctx "HLWO" puts [MqContextC::ReadSTR $ctx] } on error {} { MqContextC::ErrorCatch $ctx } finally { # delete the context using the atlmqmsgque APPLICATION-DTOR method "Exit" MqContextC::Exit $ctx }
Example from manfilter.atl
→
package require lib_85 package require atlmqmsgque namespace import ::MqContextC::* proc FTRcmd {ctx} { set ftr [SlaveGetFilter $ctx] SendSTART $ftr while {[ReadItemExists $ctx]} { SendSTR $ftr "<[ReadSTR $ctx]>" } SendEND_AND_WAIT $ftr "+FTR" SendRETURN $ctx } MqMsgque::Main { myooX::Create2N ::MqContextC ::srv ConfigSetIsServer ::srv yes ConfigSetName ::srv "filter" try { LinkCreate ::srv {*}$argv ServiceCreate ::srv "+FTR" FTRcmd ServiceProxy ::srv "+EOF" ProcessEvent ::srv MQ_WAIT_FOREVER } on error {} { ErrorCatch ::srv } finally { Exit ::srv } }
Use manfilter.atl in a atlmqmsgque command pipeline:
libmqmsgque, ccmqmsgque, csmqmsgque, javamqmsgque, gomqmsgque, pymqmsgque, rbmqmsgque, tclmqmsgque, perlmqmsgque, phpmqmsgque
Atl, unix, socket, message, msgque