libmqmsgque 9.0
Loading...
Searching...
No Matches
Modules | Macros | Typedefs
MqContextC_Config_C_API

various functions to 'config' a MqContextCMore...

+ Collaboration diagram for MqContextC_Config_C_API:

Modules

 MqContextC_ConfigApi_Misc_C_API
 various function to do 'misc' work with a MqContextC
 
 MqContextC_ConfigApi_Set_C_API
 various function to 'set' configuration-data from a MqContextC
 
 MqContextC_ConfigApi_Get_C_API
 various function to 'get' configuration-data from a MqContextC
 
 MqContextC_ConfigApi_Interface_C_API
 various function to setup a interface into MqContextC
 

Macros

#define MQ_CALLBACK_SERVICE_CALL_ARGS   MK_RT_ARGS MQ_CTX const mqctx, MK_PTR const __data__
 the MqTokenF arguments with default names
 
#define MQ_CALLBACK_SERVICE_CALL   MK_RT_CALL mqctx, __data__
 the MqTokenF arguments CALL with default names
 
#define MQ_CALLBACK_SERVICE_FREE_ARGS   MK_RT_ARGS MQ_CTX const mqctx, MK_PTR *dataP
 the MqDataFreeF arguments with default names
 
#define MQ_CALLBACK_SERVICE_COPY_ARGS   MK_RT_ARGS MQ_CTX const mqctx, MK_PTR *dataP
 the MqDataFreeF arguments with default names
 

Typedefs

typedef enum MkErrorE(* MqTokenF) (MK_RT const mkrt, MQ_CTX const ctx, MK_PTR const data)
 prototype for an object method function …
 
typedef void(* MqDataFreeF) (MK_RT const mkrt, MQ_CTX const ctx, MK_PTR *dataP)
 prototype for a free additional token data function …
 
typedef void(* MqDataCopyF) (MK_RT const mkrt, MQ_CTX const ctx, MK_PTR *dataP)
 prototype for a copy additional token data function …
 

Detailed Description

various functions to 'config' a MqContextC

The configuration is done persistent using config-api functions or on link-setup using command-line-arguments.

Options API
Naming Options
--config fileName, --name string, --prefix string, --postfix string, --ident-from prefix|factory
Startup Options
--tcp --host string --port int --myhost string --myport int, --uds --file fileName, --pipe, --thread --spawn --fork, --daemon pidfile
Runtime Options
--logfile fileName, --silent, --debug
Misc Options
--buffersize int, --pkgsize int, --timeout int, --string
Interface API
interface: void MqConfigSetServerSetup(MQ_CTX ctx, MqServiceCallbackF fCall, MK_CBP callback, MqDataFreeF fFree, MqDataCopyF fCopy)
interface: void MqConfigSetServerCleanup(MQ_CTX ctx, MqServiceCallbackF fCall, MK_CBP callback, MqDataFreeF fFree, MqDataCopyF fCopy)
interface: void MqConfigSetBgError(MQ_CTX ctx, MqServiceCallbackF fCall, MK_CBP callback, MqDataFreeF fFree, MqDataCopyF fCopy)
interface: void MqConfigSetEvent(MQ_CTX ctx, MqServiceCallbackF fEvent, MK_CBP data, MqDataFreeF fFree, MqDataCopyF fCopy)
Function API

CONFIG OPTION DETAILS

CONFIG NAMING OPTIONS DETAILS

--config fileName

set: enum MkErrorE MqConfigSetConfigFile(MQ_CTX ctx, MK_STRN filename)

add libconfig configuration file …

introduction

A config-file is used to add configuration-values to a libmqmsgque-application using a structured text-file.

supported
By default command-line-options; filter-pipline and slave-worker-setup is supported.

A service-callback and "programming" is not supported. To "programm and modify" something use a scripting language like tcl or python.

goal
The goal is to give the user of a compiled application the ability to provide a single place for common-configuration-values.

technology

libconfig is used to parse a config-file using the application … --config fileName … option.

syntax
The config-file syntax is defined at: http://hyperrealm.github.io/libconfig/libconfig_manual.html

The following restrictions apply to the --config option.

  1. The config-file is parsed when the --config option is parsed
  2. An application is identfied in the config-file by groupname : { ... } ( ":" or "=" is allowd )
  3. The groupname is the return from ClassIdentGet using hint from --ident-from prefix|factory
  4. The groupname is modified with the --name string, --prefix string or --ident-from prefix|factory naming-options
  5. The order of option-parsing is the order on the command-line
    MyClient … --XXX … --config YYY … --ZZZ …
    order MyClient : XXX < YYY < ZZZ
  6. For a pipe the config-file from the client is added to the end of the server-options :
    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
    This is required because the --name or --prefix option from DDD or EEE change the group read from the config-file
  7. attention! on a client or a non-pipe server it is a difference if the naming-option is set before or after the --config option
  8. All options set after the --config option overwrite the options from the config-file
  9. The filter ( 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

examples

1. Example from MyClient.config filter-pipeline with last server start in debug mode

# commandline OLD: MyClient @ Filter3 @ MyServer --debug 1
# commandline NEW: MyClient --config MyClient.config
version = "1.0" ; // string : version of the configuration file reader
default = "MyClient" ; // string : if the 'class' is unknown use 'default'
MyClient:
{
config:
{
# name = "myName" ; // string : displayname name of the 'context' (default: executable basename)
# identFrom = "prefix" ; // list : select how to identify the application from remote: 'prefix' or 'factory' (default: prefix)
# prefix = "" ; // string : set the 1'part of the visible displayname (default: "" = FactoryName)
# postfix = "" ; // string : set the 2'part of the visible displayname (default: "" = ConnectionName)
# string = false ; // bool : (default: no)
# startAs = "default" ; // string : from list (ref… MqStartE): default, spawn, thread, fork (default: default)
# daemon = "MyServer.pid" ; // string : file for PID
# timeout = 90 ; // int : user defined timeout to terminate a blocking function call (default: 90 sec)
# storage = "#memdb#" ; // string : storage file for the database: #memdb#, #tmpdb# or filename (default: #memdb#)
# runtime = { // struct (ref… MkRuntimeS) : runtime configuration (global)
# debug = 1 ; // int : set the debug-level, Valid values are 0 <= debug <= 9 using 0 for "no" and 9 for "max". (default: 0)
# silent = false ; // bool : write (no) or don't write (yes) any message to stdout or stderr (default: no)
# logfile = "stderr" ; // string : append to logfile, valid values are: stderr, stdout or a filename (default: stderr)
# };
# io = { // struct (ref… MqIoComE) : what kind of socket interface to use? (default: pipe)
# buffersize = 4096 // int : io buffersize (default: 4096)
# pkgsize = 10240 // int : io pkgsize (default: 10 * 1024)
# pipe = true; // struct (ref… MqIoPipeConfigS) → ONLY client (default: true)
# init = false; // struct (ref… MqIoInitConfigS) → ONLY server (default: false)
# tcp = { // struct (ref… MqIoTcpConfigS)
# port = "7777" ; // string : port number or well known port name
# host = "localhost" ; // string : hostname / interfacename
# myport = "1111" ; // string : client MY port number or well known port name
# myhost = "localhost" ; // string : client MY hostname / interfacename
# };
# uds = { // struct (ref… MqIoUdsConfigS)
# file = "filename" ; // string : name of a uds-socket-file (default: null)
# }
# };
};
# start executable "Filter3" in a "@" pipe and change application-name (groupname) to "otto"
filter = [ "Filter3", "--name", "otto" ] ; // array of string : filter pipeline name of "server"
};
# config section for "Filter3" start in the "pipe"
otto = {
filter = [ "MyServer" ] ;
}
# final "MyServer" set option "debug" to "1"
MyServer = {
config: { runtime: {debug = 1} }
# 'config.runtime.debug = 1' is NOT supported.
}

2. Example from libconfig.test filter-pipeline with last server connect by tcp/ip

# OLD: MyClient @ Filter3 @ --tcp --port $PORT
# NEW: MyClient --config configFile
version: 1.0
default = "MyClient"
MyClient: {
filter: [ "Filter3" ]
}
Filter3: {
filter: [ "--tcp", "--port", "$PORT" ]
}

--name string

attribute: MqConfigS::dispname, getter: MqConfigGetName, setter: MqConfigSetName

set the display-name of the context

The display-name is used as:

- A prefix in the local debug/error/log output:

The dispname is initialized with:

Example:
use MqConfigS::prefix and MqConfigS::postfix to set the MqConfigS::dispname :
Attention
~ the memory of MqConfigS::dispname is owned by libmqmsgque -> do not free.
~ if the dispname is NOT set the value is initialized from MqConfigS::prefix
~ to initialize the dispname by yourself use: void MqConfigSetName(MQ_CTX ctx, MK_STRN data) or --name string
~ if the --name string is explicitly set, then --prefix string and --postfix string have no effect

--prefix string

attribute: MqConfigS::prefix, getter: MqConfigGetPrefix, setter: MqConfigSetPrefix

set the server-part (1) of the application-identifer MqConfigS::dispname

The prefix is used for:

  1. MqConfigS::dispname initialization
  2. application-identifer if --ident-from prefix|factory is set to prefix (default)
  3. groupname in --config fileName is used as application-identifer

The prefix is initialize with:

  1. the basename of the executable if NO factory is used
  2. the MqFactoryS::originalIdent
  3. the void MqConfigSetPrefix(MQ_CTX ctx, MK_STRN data) or the void MqConfigSetName(MQ_CTX ctx, MK_STRN data) function
  4. the --name string OR the --prefix string option
Attention
if the --name string is explicitly set, then --prefix string and --postfix string have no effect

--postfix string

attribute: MqConfigS::postfix, getter: MqConfigGetPostfix, setter: MqConfigSetPostfix

set the client-part (2) of the application-identifer MqConfigS::dispname

The postfix is used for:

  1. MqConfigS::dispname initialization

The postfix is initialize with:

  1. an empty string
  2. the void MqConfigSetPostfix(MQ_CTX ctx, MK_STRN data) function
  3. the client postfix at server-startup
  4. the --postfix string option
Attention
if the --name string is explicitly set, then --prefix string and --postfix string have no effect

--storage fileName

attribute: MqConfigS::storage, getter: MqConfigGetStorage, setter: MqConfigSetStorage

--ident-from prefix|factory

attribute: MqConfigS::identFrom, getter: MqConfigGetIdentFrom, setter: MqConfigSetIdentFrom

select how to identify the application from remote …

An application has TWO possible names:

  1. The name from the context the application was configured with.
  2. The name from the factory the application was created with.

The --ident-from prefix|factory value decide which on is used.

The application-identification is defined by MqConfigS::identFrom :

MqFactoryS::originalIdentif ident == MQ_IDENT_FACTORY
MqConfigS::prefixif ident == MQ_IDENT_PREFIX (default)

The MqFactoryS::originalIdent is the official name of the MqFactoryC and is defined by the application-programmer with FactoryAdd or FactoryDup2.

The MqConfigS::prefix is the official name of the MqContextC that startet first, usually the server-name, and is set by the application-user with --prefix string at startup or with the ConfigSetPrefix at setup.

When the server starts, the ClassIdentGet 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: FactoryInitial.

Example: Change the factory-identifier of FactoryInitial to the value "TestClient" with:

C# MqFactoryC.Get("initial").Dup2("TestClient").Initial()
TCL [[tclmsgque::MqFactoryC Get "initial"] Dup2 "TestClient"] Initial
Attention
After link-startup the MqLinkS::targetIdent will no longer changed.

CONFIG STARTUP OPTIONS DETAILS

--tcp --host string --port int --myhost string --myport int

attribute: MqIoTcpConfigS, getter: MqConfigGetIoTcp, setter: MqConfigSetIoTcp

configure a context to use a tcp-client-server-link

Parameters
[in]hostclient: name of the remote interface (default: localhost)
server: name of the local interface (default: listen on all interfaces)
[in]portclient: name of the remote port
server: name of the local port
[in]myhostclient: name of the local interface
[in]myportclient: name of the local port

--uds --file fileName

attribute: MqIoUdsConfigS, getter: MqConfigGetIoUds, setter: MqConfigSetIoUds

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.

Parameters
[in]filename of a uds-socket-file (default: NULL)

--pipe

attribute: MqIoPipeConfigS, getter: MqConfigGetIoPipe, setter: MqConfigSetIoPipe

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.

Parameters
[in]hdlthe file-descriptor-number (default: not set)

--thread --spawn --fork

attribute: MqConfigS::startAs, getter: MqConfigGetStartAs, setter: MqConfigSetStartAs

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)

--daemon pidfile

set: enum MkErrorE MqConfigSetDaemon(MQ_CTX ctx, MK_STRN pidfile)

This option is not available for libmqmsgque.

CONFIG RUNTIME OPTIONS DETAILS

--logfile fileName

attribute: MkRuntimeS::logfile, getter: MkRuntimeGetLogfile, setter: MkRuntimeSetLogfile

--silent

attribute: MkRuntimeS::isSilent, getter: MkRuntimeGetIsSilent, setter: MkRuntimeSetIsSilent

--debug

attribute: MkRuntimeS::debug, getter: MkRuntimeGetDebug, setter: MkRuntimeSetDebug

CONFIG MISC OPTIONS DETAILS

--buffersize int

attribute: MqIoConfigS::buffersize, getter: MqConfigGetBuffersize, setter: MqConfigSetBuffersize

set the OS specific value for the socket-operation-buffer (default: OS specific)

--pkgsize int

attribute: MqIoConfigS::pkgsize, getter: MqConfigGetPkgsize, setter: MqConfigSetPkgsize

set maximum package size (default: 10 KiB)

--timeout int

attribute: MqIoConfigS::timeout, getter: MqConfigGetTimeout, setter: MqConfigSetTimeout

user defined timeout to terminate a blocking function call (default: 90 sec)

--string

attribute: MqConfigS::native, getter: MqConfigGetIsString, setter: MqConfigSetIsString

CONFIG INTERFACE API

interface: void MqConfigSetServerSetup(MQ_CTX ctx, MqServiceCallbackF fCall, MK_CBP callback, MqDataFreeF fFree, MqDataCopyF fCopy)

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 LinkCreate or LinkCreateChild. This interface is called for every new incoming connection request and is used to define context specific services using ServiceCreate or to initialize context-specific variables. As side-effect this interface set MqSetupS::isServer to MK_YES.

Read more about how to define a callback at MqContextC_ServiceApi_Callback.

interface: void MqConfigSetServerCleanup(MQ_CTX ctx, MqServiceCallbackF fCall, MK_CBP callback, MqDataFreeF fFree, MqDataCopyF fCopy)

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 LinkDelete to free context-specific variables. As side-effect this interface set MqSetupS::isServer to MK_YES.

Read more about how to define a callback at MqContextC_ServiceApi_Callback.

interface: void MqConfigSetBgError(MQ_CTX ctx, MqServiceCallbackF fCall, MK_CBP callback, MqDataFreeF fFree, MqDataCopyF fCopy)

define the background-error-interface

A background error is an error without a link to an application-context and happen if an SendEND 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.

Read more about how to define a callback at MqContextC_ServiceApi_Callback.

interface: void MqConfigSetEvent(MQ_CTX ctx, MqServiceCallbackF fEvent, MK_CBP data, MqDataFreeF fFree, MqDataCopyF fCopy)

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.

Attention
1. The Event-Handler is used to start background processing during idel-time.
2. If MqSetupS::ignoreExit is set… and the process/thread is already on shutdown… the process/thread will continue to work as long as background tasks are available.
3. The process will only exit if all Event-Handler return ErrorSetCONTINUE to signal that no other background tasks are available.
example: example/LANG/Filter4.EXT

Read more about how to define a callback at MqContextC_ServiceApi_Callback.

Macro Definition Documentation

◆ MQ_CALLBACK_SERVICE_CALL

#define MQ_CALLBACK_SERVICE_CALL   MK_RT_CALL mqctx, __data__

the MqTokenF arguments CALL with default names

Definition at line 920 of file msgque_mq.h.

◆ MQ_CALLBACK_SERVICE_CALL_ARGS

#define MQ_CALLBACK_SERVICE_CALL_ARGS   MK_RT_ARGS MQ_CTX const mqctx, MK_PTR const __data__

the MqTokenF arguments with default names

Definition at line 918 of file msgque_mq.h.

◆ MQ_CALLBACK_SERVICE_COPY_ARGS

#define MQ_CALLBACK_SERVICE_COPY_ARGS   MK_RT_ARGS MQ_CTX const mqctx, MK_PTR *dataP

the MqDataFreeF arguments with default names

Definition at line 944 of file msgque_mq.h.

◆ MQ_CALLBACK_SERVICE_FREE_ARGS

#define MQ_CALLBACK_SERVICE_FREE_ARGS   MK_RT_ARGS MQ_CTX const mqctx, MK_PTR *dataP

the MqDataFreeF arguments with default names

Definition at line 932 of file msgque_mq.h.

Typedef Documentation

◆ MqDataCopyF

typedef void( * MqDataCopyF) (MK_RT const mkrt, MQ_CTX const ctx, MK_PTR *dataP)

prototype for a copy additional token data function …

Definition at line 935 of file msgque_mq.h.

◆ MqDataFreeF

typedef void( * MqDataFreeF) (MK_RT const mkrt, MQ_CTX const ctx, MK_PTR *dataP)

prototype for a free additional token data function …

Definition at line 923 of file msgque_mq.h.

◆ MqTokenF

typedef enum MkErrorE( * MqTokenF) (MK_RT const mkrt, MQ_CTX const ctx, MK_PTR const data)

prototype for an object method function …

Definition at line 883 of file msgque_mq.h.