MqContextC_ConfigApi_C_API

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: (runtime) void MqConfigSetServerSetup(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback)
interface: (runtime) void MqConfigSetServerCleanup(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback)
interface: (runtime) void MqConfigSetBgError(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback)
interface: (runtime) void MqConfigSetEvent(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback)

Function API

CONFIG OPTION DETAILS

CONFIG NAMING OPTIONS DETAILS

--config fileName

set: (runtime) enum MkErrorE MqConfigSetConfigFile(MQ_CTX const ctx, MK_STRN const 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 allowed )
3. The groupname is the return from MqClassIdentGet 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:
  • 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 (runtime) void MqConfigSetName(MQ_CTX const ctx, MK_STRN data), (runtime) void MqConfigSetPrefix(MQ_CTX const ctx, MK_STRN data), (runtime) void MqConfigSetPostfix(MQ_CTX const ctx, MK_STRN data) 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 libmqmsgque -> do not free.
• if the dispname is NOT set the value is initialized from MqConfigS::prefix
• to initialize the dispname by yourself use: (runtime) void MqConfigSetName(MQ_CTX const 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 (runtime) void MqConfigSetPrefix(MQ_CTX const ctx, MK_STRN data) or the (runtime) void MqConfigSetName(MQ_CTX const 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 (runtime) void MqConfigSetPostfix(MQ_CTX const 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::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: MqConfigGetIoTcp, setter: MqConfigSetIoTcp
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: 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]

file

name of a uds-socket-file (default: MK_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]

hdl

the 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:

• 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:

• MQ_START_DEFAULT = 0, use application-context default entity creation
• MQ_START_FORK = 1, create entity as fork
• MQ_START_THREAD = 2, create entity as thread
• MQ_START_SPAWN = 3, create entity as spawn process

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

--daemon pidfile

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

This option is not available for libmqmsgque.

CONFIG RUNTIME OPTIONS DETAILS

--logfile fileName

attribute: MkRuntimeS::logfile, getter: RMkRuntimeGetLogfile, setter: RMkRuntimeSetLogfile

--silent

attribute: MkRuntimeS::isSilent, getter: RMkRuntimeGetIsSilent, setter: RMkRuntimeSetIsSilent

--debug

attribute: MkRuntimeS::debug, getter: RMkRuntimeGetDebug, setter: RMkRuntimeSetDebug

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
define if data is string or little or big endian …

CONFIG INTERFACE API

• IServerSetup, IServerCleanup
• IBgError, IEvent

interface: (runtime) void MqConfigSetServerSetup(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback)

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 MK_YES.

IServerSetup : callback signature

read more at Callback signature

Read more about how to define a service-callback in theLink .

interface: (runtime) void MqConfigSetServerCleanup(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback)

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 MK_YES.

IServerCleanup : callback signature

read more at Callback signature

Read more about how to define a service-callback in theLink .

interface: (runtime) void MqConfigSetBgError(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback)

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

read more at Callback signature

Read more about how to define a service-callback in theLink .

interface: (runtime) void MqConfigSetEvent(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback)

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

read more at Callback signature

Read more about how to define a service-callback in theLink .

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.