MqContextC - setup and manage a client-server-link … More...

Collaboration diagram for MqContextC_LinkApi_C_API:

Data Structures
struct	MqLinkSlaveS
	needed to "run-over-all-slaves" → example: MqRouteGetTree More...

struct	MqLinkS
	object responsible to manage a client/server link data More...

Functions
MQ_EXTERN enum MkErrorE	MqLinkCreate_RT (MK_RT const mkrt, MQ_CTX const ctx, MK_BAC args)
	make ctx to a parent-context and setup a new client-server-link …

MQ_EXTERN enum MkErrorE	MqLinkConnect_RT (MK_RT const mkrt, MQ_CTX const ctx)
	re-connect a client-server-link after a server crash or a network downtime …

MQ_EXTERN enum MkErrorE	MqLinkShutdown_RT (MK_RT const mkrt, MQ_CTX const ctx)
	shutdown the communication with a server

MQ_EXTERN enum MkErrorE	MqLinkCreateChild_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_CTX const parent, MK_BAC const args)
	make a context to a child-context on-top of an existing parent-client-server-link …

MQ_EXTERN enum MkErrorE	MqLinkDefault_RT (MK_RT const mkrt, MQ_CTX const ctx, MK_BAC const args)
	callback as wrapper for MqLinkCreate or MqLinkCreateChild with additional error-check code …

MQ_EXTERN void	MqLinkDelete_RT (MK_RT const mkrt, MQ_CTX const ctx)
	close the client-server-link …

MQ_EXTERN bool	MqLinkIsConnected (MQ_CTX const ctx) MK_ATTR_HDL
	is the context connected? …

MQ_CTX	MqLinkGetParent (MQ_CTX const ctx)
	get the initial parent-context from a client/server link …

bool	MqLinkIsParent (MQ_CTX const ctx)
	is the context a parent-context? …

MK_NUM	MqLinkGetCtxId (MQ_CTX const ctx)
	get an identifier which is unique per parent-or-child-context …

MK_STRN	MqLinkGetTargetIdent (MQ_CTX const ctx)
	get the ident of the link-target …

MqContextC - MqContextC_LinkApi_Link_C_API - function
MQ_EXTERN MQ_CTX	MqLinkGetParentP (MQ_CTX const ctx)
	Non-inline replacement for MqLinkGetParent …

MQ_EXTERN MK_NUM	MqLinkGetCtxIdP (MQ_CTX const ctx)
	Non-inline replacement for MqLinkGetCtxId …

MQ_EXTERN MK_STRN	MqLinkGetTargetIdentP (MQ_CTX const ctx)
	Non-inline replacement for MqLinkGetTargetIdent …

MQ_EXTERN MK_BOOL	MqLinkIsParentP (MQ_CTX const ctx)
	Non-inline replacement for MqLinkIsParent …

MqContextC - MqContextC_LinkApi_Link_C_API - overload
#define	MqLinkConnect_NULL(...)

#define	MqLinkConnect(...)

#define	MqLinkConnect_E(...)

#define	MqLinkConnect_C(...)

#define	MqLinkCreate_NULL(...)

#define	MqLinkCreate(...)

#define	MqLinkCreate_1(ctx)

#define	MqLinkCreate_E(...)

#define	MqLinkCreate_C(...)

#define	MqLinkCreateChild_NULL(...)

#define	MqLinkCreateChild(...)

#define	MqLinkCreateChild_2(ctx, parent)

#define	MqLinkCreateChild_E(...)

#define	MqLinkCreateChild_C(...)

#define	MqLinkDefault_NULL(...)

#define	MqLinkDefault(...)

#define	MqLinkDelete_NULL(...)

#define	MqLinkDelete(...)

#define	MqLinkShutdown_NULL(...)

#define	MqLinkShutdown(...)

#define	MqLinkShutdown_E(...)

#define	MqLinkShutdown_C(...)

Detailed Description

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"

every new client-parent-context create a new client-server-link and perform the connect system-call.
every new client-server-link start a new server-object and creating a new server-parent-context
every deletion of the client-parent-context stop the previous started server-object and delete the server-parent-context
the client-context get all the error/warning/info messages from the server-context

Definition of a "server-context"

every new server-parent-context is created by request from the client-parent-context:
in remote mode every new server-parent-context wait for a tcp or uds connection request using the accept system-call.

client --tcp --host REMOTE_HOST --port REMOTE_PORT ... or

client --uds --file MYFILE ...

in local mode new server-parent-context is started by the client-parent-context as pipe:
client @ server
- a server-context have to implement the IServerSetup and the MqFactoryC interface.
- a server-context have to enter the event-loop and wait for incoming service-request using MqProcessEvent together with the MQ_WAIT_FOREVER.

Definition of a "parent-context"

the parent is the first context created and is created with MqLinkCreate
every new parent-context on the client create a new communication to a server.
every new parent-context on the client connect to a new parent-context on the server
every new parent-context on the server create a new thread or process.
the parent-context control the socket communication interface

Definition of a "child-context"

the child-context is the second or more context and is created with MqLinkCreateChild.
every new child-context on the client create a new child-context on the server.
every new child-context is totally independent from the parent-context setup and is able to serve its own services.
the child-context is using the parent-context as a tunnel.
the child-context is using the the thread or process of the parent-context.
the parent of a child-context can be a parent-context or an other child-context. A tree like structure is created.
the child-context is using the communication interface from the parent-context.
if a context is deleted (parent or child) the depending context (parent or child) is deleted too.

Macro Definition Documentation

◆ MqLinkConnect

#define MqLinkConnect ( ... )

Value:

MqLinkConnect_RT(MK_RT_CALL __VA_ARGS__)

MK_RT_CALL

#define MK_RT_CALL

MqLinkConnect_RT

MQ_EXTERN enum MkErrorE MqLinkConnect_RT(MK_RT const mkrt, MQ_CTX const ctx)

re-connect a client-server-link after a server crash or a network downtime …

Definition at line 219 of file msgque_overload_mq.h.

◆ MqLinkConnect_C

#define MqLinkConnect_C ( ... )

Value:

if (MkErrorCheckI(MqLinkConnect(__VA_ARGS__)))

MqLinkConnect

#define MqLinkConnect(...)

Definition msgque_overload_mq.h:219

Definition at line 221 of file msgque_overload_mq.h.

◆ MqLinkConnect_E

#define MqLinkConnect_E ( ... )

Value:

MkErrorCheck(MqLinkConnect(__VA_ARGS__))

Definition at line 220 of file msgque_overload_mq.h.

◆ MqLinkConnect_NULL

#define MqLinkConnect_NULL ( ... )

Value:

MqLinkConnect_RT(MK_RT_CALL_NULL __VA_ARGS__)

MK_RT_CALL_NULL

#define MK_RT_CALL_NULL

Definition at line 218 of file msgque_overload_mq.h.

◆ MqLinkCreate

#define MqLinkCreate ( ... )

Value:

MqLinkCreate_RT(MK_RT_CALL __VA_ARGS__)

MqLinkCreate_RT

MQ_EXTERN enum MkErrorE MqLinkCreate_RT(MK_RT const mkrt, MQ_CTX const ctx, MK_BAC args)

make ctx to a parent-context and setup a new client-server-link …

Definition at line 223 of file msgque_overload_mq.h.

◆ MqLinkCreate_1

#define MqLinkCreate_1 ( ctx )

Value:

MqLinkCreate(ctx,NULL)

MqLinkCreate

#define MqLinkCreate(...)

Definition msgque_overload_mq.h:223

Definition at line 224 of file msgque_overload_mq.h.

◆ MqLinkCreate_C

#define MqLinkCreate_C ( ... )

Value:

if (MkErrorCheckI(MqLinkCreate(__VA_ARGS__)))

Definition at line 226 of file msgque_overload_mq.h.

◆ MqLinkCreate_E

#define MqLinkCreate_E ( ... )

Value:

MkErrorCheck(MqLinkCreate(__VA_ARGS__))

Definition at line 225 of file msgque_overload_mq.h.

◆ MqLinkCreate_NULL

#define MqLinkCreate_NULL ( ... )

Value:

MqLinkCreate_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 222 of file msgque_overload_mq.h.

◆ MqLinkCreateChild

#define MqLinkCreateChild ( ... )

Value:

MqLinkCreateChild_RT(MK_RT_CALL __VA_ARGS__)

MqLinkCreateChild_RT

MQ_EXTERN enum MkErrorE MqLinkCreateChild_RT(MK_RT const mkrt, MQ_CTX const ctx, MQ_CTX const parent, MK_BAC const args)

make a context to a child-context on-top of an existing parent-client-server-link …

Definition at line 228 of file msgque_overload_mq.h.

◆ MqLinkCreateChild_2

#define MqLinkCreateChild_2	(		ctx,
			parent )

Value:

MqLinkCreateChild(ctx,parent,NULL)

MqLinkCreateChild

#define MqLinkCreateChild(...)

Definition msgque_overload_mq.h:228

Definition at line 229 of file msgque_overload_mq.h.

◆ MqLinkCreateChild_C

#define MqLinkCreateChild_C ( ... )

Value:

if (MkErrorCheckI(MqLinkCreateChild(__VA_ARGS__)))

Definition at line 231 of file msgque_overload_mq.h.

◆ MqLinkCreateChild_E

#define MqLinkCreateChild_E ( ... )

Value:

MkErrorCheck(MqLinkCreateChild(__VA_ARGS__))

Definition at line 230 of file msgque_overload_mq.h.

◆ MqLinkCreateChild_NULL

#define MqLinkCreateChild_NULL ( ... )

Value:

MqLinkCreateChild_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 227 of file msgque_overload_mq.h.

◆ MqLinkDefault

#define MqLinkDefault ( ... )

Value:

MqLinkDefault_RT(MK_RT_CALL __VA_ARGS__)

MqLinkDefault_RT

MQ_EXTERN enum MkErrorE MqLinkDefault_RT(MK_RT const mkrt, MQ_CTX const ctx, MK_BAC const args)

callback as wrapper for MqLinkCreate or MqLinkCreateChild with additional error-check code …

Definition at line 233 of file msgque_overload_mq.h.

◆ MqLinkDefault_NULL

#define MqLinkDefault_NULL ( ... )

Value:

MqLinkDefault_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 232 of file msgque_overload_mq.h.

◆ MqLinkDelete

#define MqLinkDelete ( ... )

Value:

MqLinkDelete_RT(MK_RT_CALL __VA_ARGS__)

MqLinkDelete_RT

MQ_EXTERN void MqLinkDelete_RT(MK_RT const mkrt, MQ_CTX const ctx)

close the client-server-link …

Definition at line 235 of file msgque_overload_mq.h.

◆ MqLinkDelete_NULL

#define MqLinkDelete_NULL ( ... )

Value:

MqLinkDelete_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 234 of file msgque_overload_mq.h.

◆ MqLinkShutdown

#define MqLinkShutdown ( ... )

Value:

MqLinkShutdown_RT(MK_RT_CALL __VA_ARGS__)

MqLinkShutdown_RT

MQ_EXTERN enum MkErrorE MqLinkShutdown_RT(MK_RT const mkrt, MQ_CTX const ctx)

shutdown the communication with a server

Definition at line 237 of file msgque_overload_mq.h.

◆ MqLinkShutdown_C

#define MqLinkShutdown_C ( ... )

Value:

if (MkErrorCheckI(MqLinkShutdown(__VA_ARGS__)))

MqLinkShutdown

#define MqLinkShutdown(...)

Definition msgque_overload_mq.h:237

Definition at line 239 of file msgque_overload_mq.h.

◆ MqLinkShutdown_E

#define MqLinkShutdown_E ( ... )

Value:

MkErrorCheck(MqLinkShutdown(__VA_ARGS__))

Definition at line 238 of file msgque_overload_mq.h.

◆ MqLinkShutdown_NULL

#define MqLinkShutdown_NULL ( ... )

Value:

MqLinkShutdown_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 236 of file msgque_overload_mq.h.

Function Documentation

◆ MqLinkConnect_RT()

MQ_EXTERN enum MkErrorE MqLinkConnect_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx )

re-connect a client-server-link after a server crash or a network downtime …

Do nothing if the client-server-link is already connected. This function is only useful in an event-function (IEvent) if the link-disconnect (ErrorIsEXIT) is ignored (ErrorReset). Read more from the: /example/c/Filter4.c example.

Parameters

[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

Returns: The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

◆ MqLinkCreate_RT()

MQ_EXTERN enum MkErrorE MqLinkCreate_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx,
		MK_BAC	args )

make ctx to a parent-context and setup a new client-server-link …

The goal of the MqLinkCreate is to setup a link to a new server-context on the SERVER.

SERVICE CALL

The link is created with MqIoComE to a server started with MqStartE.

EXAMPLES

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:

factory-name: A known factory previous added with MqFactoryAdd.
MqFactoryAdd_1("myFeature");

...

MqLinkCreate(ctx,...,"@",myFeature,...);

MqFactoryAdd_1
#define MqFactoryAdd_1(fct)
Definition LibMqMsgque_mq.h:3484

SELF: Recognized as the initial-factory-name. (e.g. MqFactoryInitial)
The startup with "@ SELF arg1…" will be "@ executable factory-name arg1…"

WORKER: Recognized as the own executable name.
The startup from "@ WORKER arg1…" will be "@ executable arg1…"
If the ctx is not the server-context… (e.g MqSetupS::isServer == true) the default-factory (e.g. MqFactoryDefault) will be used.

The executable is defined by (static) void MqInitSetArg0(MK_BAC bfl) and will be automatical set for a non C / C++ language.

Parameters

[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

Returns: The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

◆ MqLinkCreateChild_RT()

MQ_EXTERN enum MkErrorE MqLinkCreateChild_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx,
		MQ_CTX const	parent,
		MK_BAC const	args )

make a context to a child-context on-top of an existing parent-client-server-link …

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.

Parameters

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

Returns: The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

◆ MqLinkDefault_RT()

MQ_EXTERN enum MkErrorE MqLinkDefault_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx,
		MK_BAC const	args )

callback as wrapper for MqLinkCreate or MqLinkCreateChild with additional error-check code …

The function have to be used as argument to MqCtxTypeS::Child or MqCtxTypeS::Parent as default context-create function. Return an error if an unknown command-line-argument was found.

Parameters

[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 with or without the "@" item.

Returns: The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

◆ MqLinkDelete_RT()

MQ_EXTERN void MqLinkDelete_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx )

close the client-server-link …

On a client the context will be set to not-connected and the function MqLinkIsConnected will return MK_NO. On a server the context will be deleted but only if MqSetupS::ignoreExit is not set to MK_YES. If the link is already not-connected nothing will happen.

Parameters

[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

◆ MqLinkGetCtxId()

MK_NUM MqLinkGetCtxId ( MQ_CTX const ctx )

inline

get an identifier which is unique per parent-or-child-context …

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.

Parameters

[in] ctx the MqContextS instance to work on

Returns: the identifier as number

Definition at line 5263 of file LibMqMsgque_mq.h.

                                                    {
  return ctx ? ctx->link.ctxId : 0;
};

◆ MqLinkGetCtxIdP()

MQ_EXTERN MK_NUM MqLinkGetCtxIdP ( MQ_CTX const ctx )

Non-inline replacement for MqLinkGetCtxId …

◆ MqLinkGetParent()

MQ_CTX MqLinkGetParent ( MQ_CTX const ctx )

inline

get the initial parent-context from a client/server link …

Parameters

[in] ctx the MqContextS instance to work on

Returns: the parent-context or MK_NULL if ctx is MK_NULL

Definition at line 5234 of file LibMqMsgque_mq.h.

                                                     {
  // BUF FIX: result always a context id "ctx" is valid
  // test:  Nhi1Exec lcconfig.test --block-2 --fast-testing --lang-tcl -verbose e 
  //          -match lcconfig-2-5-* --num "1 3 1" --com-uds
  //        RPC send "object-delete-message" on server-parent-context which can be
  //          a client-child. The MqLinkGetParent is used to resolve this
  // file:  LibLcConfigRpcClient.tcl
  return ctx ? MQ_GET_PARENT(ctx) : NULL;
};

◆ MqLinkGetParentP()

MQ_EXTERN MQ_CTX MqLinkGetParentP ( MQ_CTX const ctx )

Non-inline replacement for MqLinkGetParent …

◆ MqLinkGetTargetIdent()

MK_STRN MqLinkGetTargetIdent ( MQ_CTX const ctx )

inline

get the ident of the link-target …

This function is only useful if the link is up and running.

Parameters

[in] ctx the MqContextS instance to work on

Returns: get the ident of the link-target or MK_NULL if not connected

Definition at line 5274 of file LibMqMsgque_mq.h.

                                                           {
  return ctx && ctx->link.ctxIdP ? ctx->link.ctxIdP->link.targetIdent : "";
};

◆ MqLinkGetTargetIdentP()

MQ_EXTERN MK_STRN MqLinkGetTargetIdentP ( MQ_CTX const ctx )

Non-inline replacement for MqLinkGetTargetIdent …

◆ MqLinkIsConnected()

MQ_EXTERN bool MqLinkIsConnected ( MQ_CTX const ctx )

is the context connected? …

A context is connected if the MqLinkCreate command was successful. A context is not connected if:

the context has just been created and not connected
the link was deleted with MqLinkDelete

Parameters

[in] ctx the MqContextS instance to work on

Returns: a boolean value, MK_YES or MK_NO

◆ MqLinkIsParent()

bool MqLinkIsParent ( MQ_CTX const ctx )

inline

is the context a parent-context? …

A context is a parent-context if it was created with MqLinkCreate

Parameters

[in] ctx the MqContextS instance to work on

Returns: a boolean value, MK_YES or MK_NO

Definition at line 5250 of file LibMqMsgque_mq.h.

                                                  {
  return ctx ? MQ_IS_PARENT(ctx) : false;
};

◆ MqLinkIsParentP()

MQ_EXTERN MK_BOOL MqLinkIsParentP ( MQ_CTX const ctx )

Non-inline replacement for MqLinkIsParent …

◆ MqLinkShutdown_RT()

MQ_EXTERN enum MkErrorE MqLinkShutdown_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx )

shutdown the communication with a server

The following tasks are performend:

shutdown all childs
shutdown all slaves
client send the shutdown-sequence to the server
server answer the shutdown-sequence from the client
if parant … shutdown the communication infrastructure

Parameters

[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

Returns: The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Data Structures

Functions

MqContextC - MqContextC_LinkApi_Link_C_API - function

MqContextC - MqContextC_LinkApi_Link_C_API - overload

Detailed Description

Macro Definition Documentation

◆ MqLinkConnect

◆ MqLinkConnect_C

◆ MqLinkConnect_E

◆ MqLinkConnect_NULL

◆ MqLinkCreate

◆ MqLinkCreate_1

◆ MqLinkCreate_C

◆ MqLinkCreate_E

◆ MqLinkCreate_NULL

◆ MqLinkCreateChild

◆ MqLinkCreateChild_2

◆ MqLinkCreateChild_C

◆ MqLinkCreateChild_E

◆ MqLinkCreateChild_NULL

◆ MqLinkDefault

◆ MqLinkDefault_NULL

◆ MqLinkDelete

◆ MqLinkDelete_NULL

◆ MqLinkShutdown

◆ MqLinkShutdown_C

◆ MqLinkShutdown_E

◆ MqLinkShutdown_NULL

Function Documentation

◆ MqLinkConnect_RT()

◆ MqLinkCreate_RT()

◆ MqLinkCreateChild_RT()

◆ MqLinkDefault_RT()

◆ MqLinkDelete_RT()

◆ MqLinkGetCtxId()

◆ MqLinkGetCtxIdP()

◆ MqLinkGetParent()

◆ MqLinkGetParentP()

◆ MqLinkGetTargetIdent()

◆ MqLinkGetTargetIdentP()

◆ MqLinkIsConnected()

◆ MqLinkIsParent()

◆ MqLinkIsParentP()

◆ MqLinkShutdown_RT()