MqContextC - various functions to config a context … More...

Collaboration diagram for MqContextC_ConfigApi_C_API:

Topics
	MqContextC_ConfigApi_Misc_C_API
	MqContextC - various function to do 'misc' configuration …

	MqContextC_ConfigApi_Set_C_API
	MqContextC - various function to 'set' the configuration-data in a context …

	MqContextC_ConfigApi_Get_C_API
	MqContextC - various function to 'get' the configuration-data from a context …

	MqContextC_ConfigApi_Interface_C_API
	MqContextC - various function to setup a interface for the context …

Macros
#define	MQ_SERVICE_CALL_CHECK

#define	MQ_SERVICE_CALL_ARGS MK_RT_ARGS MQ_CTX const mqctx, MK_PTR const __data__
	the MqTokenF arguments with default names

#define	MQ_SERVICE_CALL MK_RT_CALL mqctx, __data__
	the MqTokenF arguments CALL with default names

#define	MQ_SERVICE_FREE_ARGS MK_RT_ARGS MQ_CTX const mqctx, MK_PTR *dataP
	the MqDataFreeF arguments with default names

#define	MQ_SERVICE_COPY_ARGS MK_RT_ARGS MQ_CTX const mqctx, MK_PTR *dataP
	the MqDataFreeF arguments with default names

Typedefs
typedef enum MkErrorE(*	MqTokenF) (MQ_SERVICE_CALL_ARGS)
	prototype for an object method function …

typedef void(*	MqDataFreeF) (MQ_SERVICE_FREE_ARGS)
	prototype for a free additional token data function …

typedef void(*	MqDataCopyF) (MQ_SERVICE_COPY_ARGS)
	prototype for a copy additional token data function …

Detailed Description

MqContextC - various functions to config a context …

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: ctx.ConfigSetServerSetup(?callback:callable=None?)
interface: ctx.ConfigSetServerCleanup(?callback:callable=None?)
interface: ctx.ConfigSetBgError(?callback:callable=None?)
interface: ctx.ConfigSetEvent(?callback:callable=None?)

Function API

CONFIG OPTION DETAILS

CONFIG NAMING OPTIONS DETAILS

--config fileName

set: ctx.ConfigSetConfigFile(filename:string)

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.

The config-file is parsed when the --config option is parsed
An application is identfied in the config-file by groupname : { ... } ( ":" or "=" is allowed )
The groupname is the return from MqClassIdentGet using hint from --ident-from prefix|factory
The groupname is modified with the --name string, --prefix string or --ident-from prefix|factory naming-options
The order of option-parsing is the order on the command-line
MyClient … --XXX … --config YYY … --ZZZ …
order MyClient : XXX < YYY < ZZZ
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
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
All options set after the --config option overwrite the options from the config-file
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: MqContextC_ConfigGetName, setter: MqContextC_ConfigSetName
set the display-name of the context …

The display-name is used as:

A prefix in the local debug/error/log output:
- C> (dispname) [2009-01-12:16-22-27] [4-0-sIoCheckArg]: option: io->com = PIPE

The dispname is initialized with:

the MqConfigS::prefix and MqConfigS::postfix value
the ctx.ConfigSetName(data:string), ctx.ConfigSetPrefix(data:string), ctx.ConfigSetPostfix(data:string) function
the --name string OR with --prefix string and --postfix string value

Example: use MqConfigS::prefix and MqConfigS::postfix to set the MqConfigS::dispname :

prefix postfix dispname

client -1-1 client-1-1

Attention

the memory of MqConfigS::dispname is owned by pymqmsgque -> do not free.
if the dispname is NOT set the value is initialized from MqConfigS::prefix
to initialize the dispname by yourself use: ctx.ConfigSetName(data:string) 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: MqContextC_ConfigGetPrefix, setter: MqContextC_ConfigSetPrefix
set the server-part (1) of the application-identifer MqConfigS::dispname …

The prefix is used for:

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

The prefix is initialize with:

the basename of the executable if NO factory is used
the MqFactoryS::originalIdent
the ctx.ConfigSetPrefix(data:string) or the ctx.ConfigSetName(data:string) function
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: MqContextC_ConfigGetPostfix, setter: MqContextC_ConfigSetPostfix
set the client-part (2) of the application-identifer MqConfigS::dispname …

The postfix is used for:

MqConfigS::dispname initialization

The postfix is initialize with:

an empty string
the ctx.ConfigSetPostfix(data:string) function
the client postfix at server-startup
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: MqContextC_ConfigGetStorage, setter: MqContextC_ConfigSetStorage

--ident-from prefix|factory

attribute: MqConfigS::identFrom, getter: MqContextC_ConfigGetIdentFrom, setter: MqContextC_ConfigSetIdentFrom
select how to identify the application from remote …

An application has TWO possible names:

The name from the context the application was configured with.
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::originalIdent	if `ident` == `MQ_IDENT_FACTORY`
MqConfigS::prefix	if `ident` == `MQ_IDENT_PREFIX` (default)

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

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

When the server starts, the MqClassIdentGet value is send from the server to the client and the client initializes the MqLinkS::targetIdent with this value. This value identifes the server from remote and is used by the MqContextC ROUTE API to select which server receive the routing-package.

The client usually get the factory and the idenfication from the: MqFactoryInitial.

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

C#	`MqFactoryC.Get("initial").Dup2("TestClient").Initial()`
TCL	`[[tclmsgque::MqFactoryC Get "initial"] Dup2 "TestClient"] Initial`

Note: After the link-start, the MqLinkS::targetIdent is no longer changed.

CONFIG STARTUP OPTIONS DETAILS

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

attribute: MqIoTcpConfigS, getter: MqContextC_ConfigGetIoTcp, setter: MqContextC_ConfigSetIoTcp
configure a context to use a tcp-client-server-link …

Parameters

[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

--uds --file fileName

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.

Parameters

[in] file name of a uds-socket-file (default: None)

--pipe

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.

Parameters

[in] hdl the file-descriptor-number (default: not set)

--thread --spawn --fork

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:

a tcp-uds-server listen on socket and get a connection-request from a client.
This require: MqFactoryC and IServerSetup .
a filter-context create a new filter-object
a server-context create a new worker-context using MqSlaveWorker
a server-context start a new client-server-link using SELF as executable-name using MqLinkCreate

The allowed integer values for MqConfigS::startAs are:

MqStartE.DEFAULT = 0, use application-context default entity creation
MqStartE.FORK = 1, create entity as fork
MqStartE.THREAD = 2, create entity as thread
MqStartE.SPAWN = 3, create entity as spawn process

(default: do not create a new application-context)

--daemon pidfile

set: ctx.ConfigSetDaemon(pidfile:string)

This option is not available for pymqmsgque.

CONFIG RUNTIME OPTIONS DETAILS

CONFIG MISC OPTIONS DETAILS

--buffersize int

attribute: MqIoConfigS::buffersize, getter: MqContextC_ConfigGetBuffersize, setter: MqContextC_ConfigSetBuffersize
set the OS specific value for the socket-operation-buffer (default: OS specific)

--pkgsize int

attribute: MqIoConfigS::pkgsize, getter: MqContextC_ConfigGetPkgsize, setter: MqContextC_ConfigSetPkgsize
set maximum package size (default: 10 KiB)

--timeout int

attribute: MqIoConfigS::timeout, getter: MqContextC_ConfigGetTimeout, setter: MqContextC_ConfigSetTimeout
user defined timeout to terminate a blocking function call (default: 90 sec)

--string

attribute: MqConfigS::native, getter: MqContextC_ConfigGetIsString, setter: MqContextC_ConfigSetIsString
define if data is string or little or big endian …

interface: ctx.ConfigSetServerSetup(?callback:callable=None?)

define the server-setup-interface (callback) used on startup …

This interface is used to configure a new server-context-link, like a constructor, and is called at the end of MqLinkCreate or MqLinkCreateChild. This interface is called for every new incoming connection request and is used to define context specific services using MqServiceCreate or to initialize context-specific variables. As side-effect this interface set MqSetupS::isServer to True.

IServerSetup : callback signature: 1. The *service-ctx* is the *context* for which the service was defined.

callback-args := service-ctx:MqContextC[in]

[static] def callback ( callback-args )

[instance] class YYY:

def callback ( self, callback-args )

[class] class ZZZ:

@staticmethod

def callback ( callback-args )

read more at: Callback signature

interface: ctx.ConfigSetServerCleanup(?callback:callable=None?)

define the server-cleanup-interface (callback) used on cleanup …

This interface is used to cleanup an old server-context-link, like a destructor, and is called at the beginning of MqLinkDelete to free context-specific variables. As side-effect this interface set MqSetupS::isServer to True.

IServerCleanup : callback signature: 1. The *service-ctx* is the *context* for which the service was defined.

callback-args := service-ctx:MqContextC[in]

[static] def callback ( callback-args )

[instance] class YYY:

def callback ( self, callback-args )

[class] class ZZZ:

@staticmethod

def callback ( callback-args )

read more at: Callback signature

interface: ctx.ConfigSetBgError(?callback:callable=None?)

define the background-error-interface …

A background error is an error without a link to an application-context and happen if an MqSendEND call fails or if an other asynchronous task fails. if the interface is not defined the error is printed to stderr and the application continue to work. if the interface is defined the context is set to error and the callback is called to process this error. Inside the callback the error is available using ErrorGetNum and ErrorGetText and can be cleared using ErrorReset.

IBgError : callback signature: 1. The *service-ctx* is the *context* for which the service was defined.

callback-args := service-ctx:MqContextC[in]

[static] def callback ( callback-args )

[instance] class YYY:

def callback ( self, callback-args )

[class] class ZZZ:

@staticmethod

def callback ( callback-args )

read more at: Callback signature

interface: ctx.ConfigSetEvent(?callback:callable=None?)

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

IEvent : callback signature: 1. The *service-ctx* is the *context* for which the service was defined.

callback-args := service-ctx:MqContextC[in]

[static] def callback ( callback-args )

[instance] class YYY:

def callback ( self, callback-args )

[class] class ZZZ:

@staticmethod

def callback ( callback-args )

read more at: Callback signature

Macro Definition Documentation

◆ MQ_SERVICE_CALL

#define MQ_SERVICE_CALL MK_RT_CALL mqctx, __data__

the MqTokenF arguments CALL with default names

Definition at line 931 of file LibMqMsgque_mq.h.

◆ MQ_SERVICE_CALL_ARGS

#define MQ_SERVICE_CALL_ARGS MK_RT_ARGS MQ_CTX const mqctx, MK_PTR const __data__

the MqTokenF arguments with default names

Definition at line 929 of file LibMqMsgque_mq.h.

◆ MQ_SERVICE_CALL_CHECK

#define MQ_SERVICE_CALL_CHECK

Value:

  do { \
  assert (__data__ != NULL); \
  if (MqCtxCheck(mqctx) == false || MkOBJ_R(mqctx).self == NULL) return MK_OK; \
} while (0)

Definition at line 922 of file LibMqMsgque_mq.h.

#define MQ_SERVICE_CALL_CHECK do { \
  assert (__data__ != NULL); \
  if (MqCtxCheck(mqctx) == false || MkOBJ_R(mqctx).self == NULL) return MK_OK; \
} while (0)

◆ MQ_SERVICE_COPY_ARGS

#define MQ_SERVICE_COPY_ARGS MK_RT_ARGS MQ_CTX const mqctx, MK_PTR *dataP

the MqDataFreeF arguments with default names

Definition at line 947 of file LibMqMsgque_mq.h.

◆ MQ_SERVICE_FREE_ARGS

#define MQ_SERVICE_FREE_ARGS MK_RT_ARGS MQ_CTX const mqctx, MK_PTR *dataP

the MqDataFreeF arguments with default names

Definition at line 939 of file LibMqMsgque_mq.h.

Typedef Documentation

◆ MqDataCopyF

typedef void( * MqDataCopyF) (MQ_SERVICE_COPY_ARGS)

prototype for a copy additional token data function …

Definition at line 950 of file LibMqMsgque_mq.h.

◆ MqDataFreeF

typedef void( * MqDataFreeF) (MQ_SERVICE_FREE_ARGS)

prototype for a free additional token data function …

Definition at line 942 of file LibMqMsgque_mq.h.

◆ MqTokenF

typedef enum MkErrorE( * MqTokenF) (MQ_SERVICE_CALL_ARGS)

prototype for an object method function …

Definition at line 892 of file LibMqMsgque_mq.h.

application	groupname	option-parsing-order
MyClient	MyClient	AAA < BBB < CCC
Filter3	otto	DDD < BBB
MyServer	MyServer	EEE < BBB

Topics

Macros

Typedefs

Detailed Description

CONFIG OPTION DETAILS

CONFIG NAMING OPTIONS DETAILS

--config fileName

introduction

technology

examples

--name string

--prefix string

--postfix string

--storage fileName

--ident-from prefix|factory

CONFIG STARTUP OPTIONS DETAILS

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

--uds --file fileName

--pipe

--thread --spawn --fork

--daemon pidfile

CONFIG RUNTIME OPTIONS DETAILS

--logfile fileName

--silent

--debug

CONFIG MISC OPTIONS DETAILS

--buffersize int

--pkgsize int

--timeout int

--string

CONFIG INTERFACE API

interface: ctx.ConfigSetServerSetup(?callback:callable=None?)

interface: ctx.ConfigSetServerCleanup(?callback:callable=None?)

interface: ctx.ConfigSetBgError(?callback:callable=None?)

interface: ctx.ConfigSetEvent(?callback:callable=None?)

Macro Definition Documentation

◆ MQ_SERVICE_CALL

◆ MQ_SERVICE_CALL_ARGS

◆ MQ_SERVICE_CALL_CHECK

◆ MQ_SERVICE_COPY_ARGS

◆ MQ_SERVICE_FREE_ARGS

Typedef Documentation

◆ MqDataCopyF

◆ MqDataFreeF

◆ MqTokenF