MqContextC_MiscApi_C_API

MqContextC - various functions to work on a context … More...

Collaboration diagram for MqContextC_MiscApi_C_API:

Functions
MQ_CTX	MqGetRoot (MQ_CTX ctx)
	get the Root (toplevel initial context)
MQ_CTXN	MqGetRootN (MQ_CTXN ctx)
	(const) get the Root (toplevel initial context)
MQ_EXTERN void	MqExit_RT (MK_RT const mkrt, MQ_CTX const ctx, MK_STRN const callfunc, MK_STRN const callfile, MK_I32 const callline) MK_NO_RETURN
	delete the context and exit the current process or thread …
MQ_EXTERN void	MqContextMark_RT (MK_RT const mkrt, MQ_CTX const ctx)
	Mark objects as used to avoid the freeing of used external memory in an external Garbage-Collection …
MQ_EXTERN enum MkErrorE	MqCheckForLeftOverArguments_RT (MK_RT const mkrt, MQ_CTX const ctx, MK_BFLN args)
	check for left over arguments from parameter args of MqLinkCreate …
MQ_EXTERN MK_BUF	MqContextGetBuffer_RT (MK_RT const mkrt, MQ_CTX const ctx)
	get the MqContextS::ctxbuf object
MQ_EXTERN enum MkErrorE	MqProcessEvent_RT (MK_RT const mkrt, MQ_CTX const ctx, enum MqWaitOnEventE const wait, MK_TIME_T timeout)
	enter the event-loop and wait for an incoming service-request. …
MQ_EXTERN MK_STRN	MqContextToString_RT (MK_RT const mkrt, MQ_CTXN const ctx)
	String-Slot - returns the string representation of the inst …

MqContextC - MqContextC_MiscApi_Misc_C_API - function
MQ_EXTERN MQ_CTX	MqGetRootP (MQ_CTX ctx)
	Non-inline replacement for MqGetRoot …

MqContextC - MqContextC_MiscApi_Misc_C_API - overload
#define	MqContextGetBuffer_NULL(...)
#define	MqContextGetBuffer(...)
#define	MqCheckForLeftOverArguments_NULL(...)
#define	MqCheckForLeftOverArguments(...)
#define	MqCheckForLeftOverArguments_E(...)
#define	MqCheckForLeftOverArguments_C(...)
#define	MqContextMark_NULL(...)
#define	MqContextMark(...)
#define	MqContextToString_NULL(...)
#define	MqContextToString(...)
#define	MqExit_NULL(...)
#define	MqExit(...)
#define	MqExit_3(ctx, callfunc, callfile)
#define	MqExit_2(ctx, callfunc)
#define	MqExit_1(ctx)
#define	MqProcessEvent_NULL(...)
#define	MqProcessEvent(...)
#define	MqProcessEvent_2(ctx, wait)
#define	MqProcessEvent_1(ctx)
#define	MqProcessEvent_E(...)
#define	MqProcessEvent_C(...)

Detailed Description

MqContextC - various functions to work on a context …

Macro Definition Documentation

MqCheckForLeftOverArguments

#define MqCheckForLeftOverArguments

(

...

)

Value:

MqCheckForLeftOverArguments_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 306 of file msgque_overload_mq.h.

MqCheckForLeftOverArguments_C

#define MqCheckForLeftOverArguments_C

(

...

)

Value:

if (MkErrorCheckI(MqCheckForLeftOverArguments(__VA_ARGS__)))

Definition at line 308 of file msgque_overload_mq.h.

MqCheckForLeftOverArguments_E

#define MqCheckForLeftOverArguments_E

(

...

)

Value:

MkErrorCheck(MqCheckForLeftOverArguments(__VA_ARGS__))

Definition at line 307 of file msgque_overload_mq.h.

MqCheckForLeftOverArguments_NULL

#define MqCheckForLeftOverArguments_NULL

(

...

)

Value:

MqCheckForLeftOverArguments_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 305 of file msgque_overload_mq.h.

MqContextGetBuffer

#define MqContextGetBuffer

(

...

)

Value:

MqContextGetBuffer_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 302 of file msgque_overload_mq.h.

MqContextGetBuffer_NULL

#define MqContextGetBuffer_NULL

(

...

)

Value:

MqContextGetBuffer_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 301 of file msgque_overload_mq.h.

MqContextMark

#define MqContextMark

(

...

)

Value:

MqContextMark_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 310 of file msgque_overload_mq.h.

MqContextMark_NULL

#define MqContextMark_NULL

(

...

)

Value:

MqContextMark_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 309 of file msgque_overload_mq.h.

MqContextToString

#define MqContextToString

(

...

)

Value:

MqContextToString_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 312 of file msgque_overload_mq.h.

MqContextToString_NULL

#define MqContextToString_NULL

(

...

)

Value:

MqContextToString_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 311 of file msgque_overload_mq.h.

MqExit

#define MqExit

(

...

)

Value:

MqExit_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 314 of file msgque_overload_mq.h.

MqExit_1

#define MqExit_1

(

ctx

)

Value:

MqExit(ctx,__func__,__FILE__,__LINE__)

Definition at line 317 of file msgque_overload_mq.h.

MqExit_2

#define MqExit_2	(		ctx,
			callfunc )

Value:

MqExit(ctx,callfunc,__FILE__,__LINE__)

Definition at line 316 of file msgque_overload_mq.h.

MqExit_3

#define MqExit_3	(		ctx,
			callfunc,
			callfile )

Value:

MqExit(ctx,callfunc,callfile,__LINE__)

Definition at line 315 of file msgque_overload_mq.h.

MqExit_NULL

#define MqExit_NULL

(

...

)

Value:

MqExit_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 313 of file msgque_overload_mq.h.

MqProcessEvent

#define MqProcessEvent

(

...

)

Value:

MqProcessEvent_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 319 of file msgque_overload_mq.h.

MqProcessEvent_1

#define MqProcessEvent_1

(

ctx

)

Value:

MqProcessEvent(ctx,MQ_WAIT_NO,MK_TIMEOUT_DEFAULT)

Definition at line 321 of file msgque_overload_mq.h.

MqProcessEvent_2

#define MqProcessEvent_2	(		ctx,
			wait )

Value:

MqProcessEvent(ctx,wait,MK_TIMEOUT_DEFAULT)

Definition at line 320 of file msgque_overload_mq.h.

MqProcessEvent_C

#define MqProcessEvent_C

(

...

)

Value:

if (MkErrorCheckI(MqProcessEvent(__VA_ARGS__)))

Definition at line 323 of file msgque_overload_mq.h.

MqProcessEvent_E

#define MqProcessEvent_E

(

...

)

Value:

MkErrorCheck(MqProcessEvent(__VA_ARGS__))

Definition at line 322 of file msgque_overload_mq.h.

MqProcessEvent_NULL

#define MqProcessEvent_NULL

(

...

)

Value:

MqProcessEvent_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 318 of file msgque_overload_mq.h.

Function Documentation

MqCheckForLeftOverArguments_RT()

MQ_EXTERN enum MkErrorE MqCheckForLeftOverArguments_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx,
		MK_BFLN	args )

check for left over arguments from parameter args of MqLinkCreate …

This code is not part of MqLinkCreate because sometimes it is necessary to check for left over arguments after MqLinkCreate was called and after the calling function was able to process function specific arguments. By Default MqLinkCreate will delete all arguments belonging to libmqmsgque from the args object. If the calling function does not expect additional arguments or arguments were added with spelling errors, a call to MqCheckForLeftOverArguments will detect this.

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,out]	args	the argument-list to check for left-over arguments

Returns

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

See also

BufferListCreate

MqContextGetBuffer_RT()

MQ_EXTERN MK_BUF MqContextGetBuffer_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx )

get the MqContextS::ctxbuf object

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 context->ctxbuf object

Attention

(do not free) The memory of the out/return value belongs to the called LibMqMsgque function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MqContextMark_RT()

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

Mark objects as used to avoid the freeing of used external memory in an external Garbage-Collection …

An external Garbage-Collection (GC) need information about external objects referenced by libmqmsgque. This objects are the MK_PTR data parameter required by different functions.

To finally mark the object the MqCtxTypeS::dataMF and/or MqCtxTypeS::callbackMF functions are used.

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

Attention

This function is only used by RUBY

MqContextToString_RT()

MQ_EXTERN MK_STRN MqContextToString_RT	(	MK_RT const	mkrt,
		MQ_CTXN const	ctx )

String-Slot - returns the string representation of the inst …

The string is a human-readable form of the data stored in the object.

See also

slot: every class should provide a ToString function by default.

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 requested string or "MK_NULL" on error

Note

(do not free) The memory of the out/return value belongs to the called LibMqMsgque function and therefore never becomes MK_NULL for a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.

MqExit_RT()

MQ_EXTERN void MqExit_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx,
		MK_STRN const	callfunc,
		MK_STRN const	callfile,
		MK_I32 const	callline )

delete the context and exit the current process or thread …

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]	callfunc	a user-defined postfix to identify the calling function or the environment (default=name-of-function)
[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 libmqmsgque, does exit but the process continue to work. To make it short use MqExit to exit your application.

The following steps are performed:

• delete the client-server-link using: MqLinkDelete
• if available call the context-specific-exit-handler: MqCtxTypeS::fProcessExit
• or call application-default-exit-handler
• it is a panic-error to call MqExit twice for the same object

Attention

It is a bad practice to call MqExit from inside a service.

• To trigger an exit in a service use the MkErrorSetEXIT exception.
• The MkErrorSetEXIT is an attribute of the MkErrorC class.
• The MkErrorC class is available with:
  1. MkErrorFORMAT from MkErrorC
  2. MqContextErrorFORMAT from MqContextC

potential problems

1. If you call MqExit on a service in a c++ (p)thread on linux … an SIGABRT is raised… ??? this problem is related with the "internal thread cleanup"… call ErrorSetEXIT to exit from a service handle

MqGetRoot()

MQ_CTX MqGetRoot ( MQ_CTX ctx )

inline

get the Root (toplevel initial context)

Definition at line 4417 of file LibMqMsgque_mq.h.

                                       {
  return ctx ? (MQ_IS_SLAVE(ctx) ? MqGetRoot(ctx->config.master) : MQ_GET_PARENT(ctx)) : NULL;
}

Here is the caller graph for this function:

MqGetRootN()

MQ_CTXN MqGetRootN ( MQ_CTXN ctx )

inline

(const) get the Root (toplevel initial context)

Definition at line 4423 of file LibMqMsgque_mq.h.

                                          {
  return ctx ? (MQ_IS_SLAVE(ctx) ? MqGetRoot(ctx->config.master) : MQ_GET_PARENT(ctx)) : NULL;
}

MqGetRootP()

MQ_EXTERN MQ_CTX MqGetRootP

(

MQ_CTX

ctx

)

Non-inline replacement for MqGetRoot …

MqProcessEvent_RT()

MQ_EXTERN enum MkErrorE MqProcessEvent_RT	(	MK_RT const	mkrt,
		MQ_CTX const	ctx,
		enum MqWaitOnEventE const	wait,
		MK_TIME_T	timeout )

enter the event-loop and wait for an incoming service-request. …

This function is used to enter the event-loop and start listen on open file-handles and to call IEvent 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.

Attention

Be aware that the read-data-package is only valid until the event-loop is entered. During event-loop new data may be available for the ctx and the read-data-package will be overwritten.

See also

MqRouteTraverse

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]	wait	the operation-mode used to define the behaviour, possible values are: MQ_WAIT_NO 0 Check for one event but do not wait … If an event is available process the event, but only one. If no event is available return with MK_CONTINUE. This is the default. MQ_WAIT_ONCE 1 Wait maximum timeout seconds for one new event, doesn't matter which context the event belongs to or raise an timeout-error … attention: During serving an event and this event uses the MqContextC SEND API or an other MqProcessEvent … an additional event could be served as well. error: An asynchronous error (_ERR) always belong to the parent-context of the socket connection if (runtime) void MqConfigSetBgError(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback) is set.. the current context returns MK_OK. if (runtime) void MqConfigSetBgError(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback) is not set.. the current context the returns MK_ERROR and an error is raised. MQ_WAIT_OWN 2 Wait maximum timeout seconds for one new event that belongs to the current context or raise an timeout-error … error: An asynchronous error (_ERR) always belong to the parent-context of the socket connection if (runtime) void MqConfigSetBgError(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback) is set.. the current context will not return and continue working. if (runtime) void MqConfigSetBgError(MQ_CTX const ctx, MqServiceCallbackF fCall, MK_CBP callback) is not set.. the current context returns MK_ERROR and an error is raised. MQ_WAIT_FOREVER 3 Wait maximum timeout seconds for an event or raise an timeout-error … If an event was found process the event. If an event was not found, raise a timeout-error. After the event was processed continue to listen for a the new event. This function will only come back on error or on exit.
[in]	timeout	in seconds until a timeout-error is raised, possible values are: integer >0 use this value as number of seconds. MK_TIMEOUT_DEFAULT -1 MK_TIMEOUT_USER for MQ_WAIT_ONCE or MK_TIMEOUT_MAX for MQ_WAIT_FOREVER. - request the default timeout value MK_TIMEOUT_USER -2 request the user defined timeout value from MqIoConfigS::timeout MK_TIMEOUT_MAX -3 request the maximum possible (infinite) timeout value

Returns

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