MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service … More...
Functions | |
MQ_EXTERN enum MkErrorE | libmqmsgque::MqSendEND_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MK_TIME_T timeout) |
MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service … | |
MQ_EXTERN enum MkErrorE | libmqmsgque::MqSendSTART_RT (MK_RT const mkrt, MQ_CTX const ctx) |
initialize the send-data-package. … | |
MQ_EXTERN enum MkErrorE | libmqmsgque::MqSendEND_AND_WAIT_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MK_TIME_T timeout) |
finish the send-data-block, call the remote service and wait for result… | |
MQ_EXTERN enum MkErrorE | libmqmsgque::MqSendEND_AND_TRANSACTION_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MQ_TOK const callback, MK_TIME_T timeout) |
finish the send-data-block, call the remote service to do a longterm-transaction-call … | |
MQ_EXTERN enum MkErrorE | libmqmsgque::MqSendEND_AND_SUB_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MqServiceCallbackF const fCall, MK_CBP callback, MqDataFreeF fFree, MK_TIME_T timeout) |
finish the send-data-block, call the remote service, do wait for the result and expect multiple sub-results on a callback … | |
MQ_EXTERN enum MkErrorE | libmqmsgque::MqSendEND_AND_CALLBACK_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MqServiceCallbackF const fCall, MK_CBP callback, MqDataFreeF fFree, MK_TIME_T const timeout) |
finish the send-data-block, call the remote service, do not-wait for the result but expect the result on a callback … | |
MQ_EXTERN enum MkErrorE | libmqmsgque::MqSendSYNC_RT (MK_RT const mkrt, MQ_CTX const ctx) |
garantee that all pending asynchronous-service-calls are processed. … | |
MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service …
calling a remote service and wait timeout seconds for an result. If timeout == 0
it is an asynchronous-service-call and if the timeout > 0
it is a synchronous-service-call.
service-call | blocking | timeout |
---|---|---|
synchronous | yes | timeout > 0 |
asynchronous | no | timeout == 0 |
blocking mean waiting max timeout seconds to finishing the service-call:
If an error was raised on the server during the service-processing… the following error-handling will be available
[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] | token | the MqContextC SERVICE API to identify the service |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (libmkkernel::MK_TIMEOUT_DEFAULT=0 ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
#define MqSendEND | ( | ... | ) |
Definition at line 634 of file msgque_overload_mq.h.
#define MqSendEND_2 | ( | ctx, | |
token ) |
Definition at line 635 of file msgque_overload_mq.h.
#define MqSendEND_AND_CALLBACK | ( | ... | ) |
Definition at line 639 of file msgque_overload_mq.h.
#define MqSendEND_AND_CALLBACK_C | ( | ... | ) |
Definition at line 641 of file msgque_overload_mq.h.
#define MqSendEND_AND_CALLBACK_E | ( | ... | ) |
Definition at line 640 of file msgque_overload_mq.h.
#define MqSendEND_AND_CALLBACK_NULL | ( | ... | ) |
Definition at line 638 of file msgque_overload_mq.h.
#define MqSendEND_AND_SUB | ( | ... | ) |
Definition at line 643 of file msgque_overload_mq.h.
#define MqSendEND_AND_SUB_C | ( | ... | ) |
Definition at line 645 of file msgque_overload_mq.h.
#define MqSendEND_AND_SUB_E | ( | ... | ) |
Definition at line 644 of file msgque_overload_mq.h.
#define MqSendEND_AND_SUB_NULL | ( | ... | ) |
Definition at line 642 of file msgque_overload_mq.h.
#define MqSendEND_AND_TRANSACTION | ( | ... | ) |
Definition at line 647 of file msgque_overload_mq.h.
#define MqSendEND_AND_TRANSACTION_3 | ( | ctx, | |
token, | |||
callback ) |
Definition at line 648 of file msgque_overload_mq.h.
#define MqSendEND_AND_TRANSACTION_C | ( | ... | ) |
Definition at line 650 of file msgque_overload_mq.h.
#define MqSendEND_AND_TRANSACTION_E | ( | ... | ) |
Definition at line 649 of file msgque_overload_mq.h.
#define MqSendEND_AND_TRANSACTION_NULL | ( | ... | ) |
Definition at line 646 of file msgque_overload_mq.h.
#define MqSendEND_AND_WAIT | ( | ... | ) |
Definition at line 652 of file msgque_overload_mq.h.
#define MqSendEND_AND_WAIT_2 | ( | ctx, | |
token ) |
Definition at line 653 of file msgque_overload_mq.h.
#define MqSendEND_AND_WAIT_C | ( | ... | ) |
Definition at line 655 of file msgque_overload_mq.h.
#define MqSendEND_AND_WAIT_E | ( | ... | ) |
Definition at line 654 of file msgque_overload_mq.h.
#define MqSendEND_AND_WAIT_NULL | ( | ... | ) |
Definition at line 651 of file msgque_overload_mq.h.
#define MqSendEND_C | ( | ... | ) |
Definition at line 637 of file msgque_overload_mq.h.
#define MqSendEND_E | ( | ... | ) |
Definition at line 636 of file msgque_overload_mq.h.
#define MqSendEND_NULL | ( | ... | ) |
Definition at line 633 of file msgque_overload_mq.h.
#define MqSendSTART | ( | ... | ) |
Definition at line 657 of file msgque_overload_mq.h.
#define MqSendSTART_C | ( | ... | ) |
Definition at line 659 of file msgque_overload_mq.h.
#define MqSendSTART_E | ( | ... | ) |
Definition at line 658 of file msgque_overload_mq.h.
#define MqSendSTART_NULL | ( | ... | ) |
Definition at line 656 of file msgque_overload_mq.h.
#define MqSendSYNC | ( | ... | ) |
Definition at line 661 of file msgque_overload_mq.h.
#define MqSendSYNC_C | ( | ... | ) |
Definition at line 663 of file msgque_overload_mq.h.
#define MqSendSYNC_E | ( | ... | ) |
Definition at line 662 of file msgque_overload_mq.h.
#define MqSendSYNC_NULL | ( | ... | ) |
Definition at line 660 of file msgque_overload_mq.h.
MQ_EXTERN enum MkErrorE libmqmsgque::MqSendEND_AND_CALLBACK_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MqServiceCallbackF const | fCall, | ||
MK_CBP | callback, | ||
MqDataFreeF | fFree, | ||
MK_TIME_T const | timeout ) |
finish the send-data-block, call the remote service, do not-wait for the result but expect the result on a callback …
This function will never block and return immediately. Usually multiple MqSendEND_AND_CALLBACK are send and finally multiple MqProcessEvent are called to wait for the results.
Example from route_mq.c
→ (C) call a service using a callback
Be aware of the followig limitatitions if multiple MqSendEND_AND_CALLBACK are called with different ctx:
[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] | token | the MqContextC SERVICE API to identify the service |
[in] | fCall | the function to process the service-call results |
[in] | callback | a user defined additional data-argument for the callback function (C-API only) |
[in] | fFree | the function to free the data-argument after use (C-API only) |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (libmkkernel::MK_TIMEOUT_DEFAULT= 0) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqSendEND_AND_CALLBACK
: callback overloadMqSendEND_AND_CALLBACK
: callback signatureMQ_EXTERN enum MkErrorE libmqmsgque::MqSendEND_AND_SUB_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MqServiceCallbackF const | fCall, | ||
MK_CBP | callback, | ||
MqDataFreeF | fFree, | ||
MK_TIME_T | timeout ) |
finish the send-data-block, call the remote service, do wait for the result and expect multiple sub-results on a callback …
The goal of this service-call is, to split a big data-block into multiple pieces. A typical solution would be a database-application doing a select and sending EVERY row as a ctx.SendRETURN_SUB()
. At the end ONE final and EMPTY ctx.SendRETURN()
is used to delete the open transaction and finish the service call.
[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] | token | the MqContextC SERVICE API to identify the service |
[in] | fCall | the function to process the service-call results |
[in] | callback | a user defined additional data-argument for the callback function (C-API only) |
[in] | fFree | the function to free the data-argument after use (C-API only) |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (libmkkernel::MK_TIMEOUT_DEFAULT=libmkkernel::MK_TIMEOUT_USER ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
ctx.SendRETURN()
) is only called if the packet contains a data-item or on an error. If the packet is empty, only the transaction is closed.MqSendEND_AND_SUB
: callback overloadMqSendEND_AND_SUB
: callback signatureMQ_EXTERN enum MkErrorE libmqmsgque::MqSendEND_AND_TRANSACTION_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MQ_TOK const | callback, | ||
MK_TIME_T | timeout ) |
finish the send-data-block, call the remote service to do a longterm-transaction-call …
A longterm-transaction is a service-call with guaranteed delivery. guaranteed mean that the transaction is using the MqContextC STORAGE API to keep every step persistent being able to recover a step if something unexpected happen.
To link the result with the calling-environment a private transaction-item is used to save the calling-environment to the local-storage. If the local-storage is persistent, the calling-environment will even survive an application restart.
If the result from the public service-call arrives, the transaction-item will be extracted from the result and the private calling-environment will be initialized from the local-storage.
To create a persistent-transaction the MqContextC STORAGE API have to be setup as persistent. By default, an in-memory MqContextC STORAGE API is used.
The longterm-transaction-call has TWO results…
In difference to MqSendEND_AND_WAIT and MqSendEND_AND_CALLBACK a longterm-transaction-call have to survive an application restart. To achieve this goal… two features have to be available to process the results:
The transaction-item is the entry-id from the local internal database and is the public handle of the private data. If the transaction-item-private-data should be persistent (survive an application restart) the internal database have to be persistent using the Storage option.
The transaction-item-private-data requires a MqSendT_START … MqSendT_END at the beginning of the send-data-package.
The list of data-items in the transaction-item-private-data have to be provided by the programmer and is used to initialise the environment in the callback (for example an external database-entry-id).
In the transaction-callback the transaction-item-private-data have to be extracted with MqReadT_START … MqReadT_END at the beginning of the read-data-package.
The transaction-callback have to be a MqContextC_ServiceApi_Identifer defined with MqServiceCreate in the application setup code (like IServerSetup) and have to be available after an application restart.
If an error is raised on the server during the database-insert the function will return this error immediately. During waiting for the return the event-loop is used to process other events. Use IEvent to add your tasks into the event loop.
[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] | token | the MqContextC SERVICE API to identify the service |
[in] | callback | the MqContextC_ServiceApi_Identifer of the MqContextC_ServiceApi_Callback |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (libmkkernel::MK_TIMEOUT_DEFAULT=libmkkernel::MK_TIMEOUT_USER ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
Example from MyTransaction.cc
→ make a logterm-transaction-call using the LOW and the HIGH api
#include <iostream> using namespace ccmqmsgque; void callback(MqContextC *ctx) { ctx->ReadT_START(); MK_STRN myPrivateHandle = ctx->ReadSTR(); ctx->ReadT_END(); MK_I32 myServiceResult = ctx->ReadI32(); std::cout << "myPrivateHandle=" << myPrivateHandle << ", myServiceResult=" << myServiceResult << std::endl; } int MK_CDECL main(int argc, MK_STRN argv[]) { MqMsgque::Setup(); MqContextC ctx; try { ctx.ConfigSetName("MyTransaction"); // setup commandline arguments used for parsing MkBufferListC args = {argc, argv}; // check if the '--token' option is available, default "SRVC" MK_STRN token = args.CheckOptionSTR("--token", "SRVC"); // connect to the server ctx.LinkCreate(args); // register callback ctx.ServiceCreate("CLB1", MqContextC::MqTokenCCB(callback)); // send block using the LOW-Api ctx.SendSTART(); ctx.SendT_START(); ctx.SendSTR("Privat_Data_1"); ctx.SendT_END(); ctx.SendI32(11111); ctx.SendEND_AND_TRANSACTION(token, "CLB1"); // send block using the HIGN-Api -> same as above, but shorter char buffer[30]; sprintf(buffer, "%s:(C)I",token); ctx.Send("T", "CLB1", buffer, "Privat_Data_2", 22222); // now we wait for exact ONE result of the "ctx" ctx.ProcessEvent(MQ_WAIT_OWN); } catch (const std::exception& e) { ctx.ErrorCatch(e); } ctx.Exit(); }
MQ_EXTERN enum MkErrorE libmqmsgque::MqSendEND_AND_WAIT_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MK_TIME_T | timeout ) |
finish the send-data-block, call the remote service and wait for result…
If an error is raised on the server during the service-processing the function will return this error immediately. During waiting for the return the event-loop is used to process other events. Use IEvent to add your tasks into the event loop.
[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] | token | the MqContextC SERVICE API to identify the service |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (libmkkernel::MK_TIMEOUT_DEFAULT=libmkkernel::MK_TIMEOUT_USER ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MQ_EXTERN enum MkErrorE libmqmsgque::MqSendEND_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MK_TIME_T | timeout ) |
MqContextC - finish the send-data-block and call synchronous/asynchronous a remote-service …
calling a remote service and wait timeout seconds for an result. If timeout == 0
it is an asynchronous-service-call and if the timeout > 0
it is a synchronous-service-call.
service-call | blocking | timeout |
---|---|---|
synchronous | yes | timeout > 0 |
asynchronous | no | timeout == 0 |
blocking mean waiting max timeout seconds to finishing the service-call:
If an error was raised on the server during the service-processing… the following error-handling will be available
[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] | token | the MqContextC SERVICE API to identify the service |
[in] | timeout | in seconds until a timeout-error is raised (possible values like ProcessEvent) (libmkkernel::MK_TIMEOUT_DEFAULT=0 ) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
initialize the send-data-package. …
This function must be the first statement in a send-data-block.
If the socket is closed or failed, the connection is established with a MqLinkConnect.
Note that during MqLinkConnect the event-loop is called and your read-data-package may be invalid.
It is recommended to perform all READ operations first and then all SEND operations.
From MqSendSTART to MqSendEND is a send-data-block and no event-loop action is allowed between them.
The event-loop could modify the already started send-data-package and corrupt the data.
[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 |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
garantee that all pending asynchronous-service-calls are processed. …
The asynchronous-service-call is defined at: MqContextC_ServiceApi_C_API.
All service-calls to a specific ctx are queued in a service-call-pipeleine. The synchronous-service-call is blocking the service-call-pipeleine until the synchronous-service-call is finished. The asynchronous-service-call does NOT blocking the pipeline and so all asynchronous-service-call are processed in parallel. The MqSendSYNC is used if multiple asynchronous-service-calls are done to a single ctx and this ctx should be blocked until all asynchronous-service-calls are finished. The MqSendSYNC is just an normal blocking synchronous-service-call which is only finished after all asynchronous-service-calls are finished.
Example from perfclient.c
→ sending a bulk of asynchronous-sevice-requests
The last MqSendSYNC garantee the all previous asynchronous-service-calls are finished.