MqContextC - create and manage a service … More...
Topics | |
MqContextC_ServiceApi_Identifer | |
MqContextC - a char[4+1] or hex[8+1] string used to unique identify a service … | |
MqContextC_ServiceApi_Callback | |
Service callback summary … | |
Macros | |
#define | MQ_TOK_SIZE (8+1) |
maximum size of the MQ_TOK … | |
Typedefs | |
typedef MK_STRN | MQ_TOK |
MqContextC - a char[4+1] or hex[8+1] string used to unique identify a service … | |
typedef MqTokenF | MqServiceCallbackF |
MqContextC - the callback-function is used as a service-handle or as a event-handle … | |
Functions | |
MK_ATTR_HDL bool | MqServiceIsTransaction (MQ_CTX const ctx) |
check if the ongoing-service-call belongs to a transaction … | |
MQ_EXTERN MQ_TOK | MqServiceTokenGet (MQ_CTX const ctx) MK_ATTR_HDL |
in an ongoing-service-call get the current MqContextC_ServiceApi_Identifer … | |
MQ_EXTERN bool | MqServiceTokenCheck (MQ_CTX const ctx, MQ_TOK const token) MK_ATTR_HDL |
in an ongoing-service-call check if the current MqContextC_ServiceApi_Identifer is token … | |
MQ_EXTERN bool | MqServiceTokenExists (MQ_CTX const ctx, MQ_TOK const token) MK_ATTR_HDL |
check if the MqContextC_ServiceApi_Identifer token is defined as ctx service … | |
MQ_EXTERN enum MkErrorE | MqServiceCreate_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MqServiceCallbackF const fCall, MK_CBP callback, MqDataFreeF fFree, MkMarkF fMark) |
create a link between a service-token and a service-callback … | |
MQ_EXTERN enum MkErrorE | MqServiceStorage_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token) |
setup a service listen on a MqContextC_ServiceApi_Identifer and save all read-data-package into the STORAGE … | |
MQ_EXTERN enum MkErrorE | MqServiceDelete_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token) |
delete a service. … | |
MqServiceProxy | |||||||||||||||
create a service to link a master-context with a slave-context. … This function is used to create a proxy-service to forward the body-data from the read-data-package of the master to the send-data-package of the slave. The data is not changed. This function support the reverse-operation also. If the ctx is a master-context than the data is send to slave identified by id. If the ctx is a slave-context than the data is send to the master of the slave.
| |||||||||||||||
MQ_EXTERN enum MkErrorE | MqServiceProxy_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MQ_SLAVE_ID const id) | ||||||||||||||
create a service to link a master-context with a slave-context. … | |||||||||||||||
MQ_EXTERN enum MkErrorE | MqServiceProxyCtx_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MQ_CTX const target) | ||||||||||||||
same as MqServiceProxy but use an MqContextC as input. | |||||||||||||||
MQ_EXTERN enum MkErrorE | MqServiceProxyRoundRobin_RT (MK_RT const mkrt, MQ_CTX const ctx, MQ_TOK const token, MK_STRN const ident) | ||||||||||||||
create a proxy-service using Round-Robin as load-balancer … | |||||||||||||||
MQ_EXTERN bool | MqServiceProxyCtxExists (MQ_CTX const ctx, MQ_TOK const token, MQ_CTX const target) | ||||||||||||||
check if service who belongs to token is a proxy-service | |||||||||||||||
MqContextC - MqContextC_ServiceApi_Service_C_API - function | |
MK_BOOL | MqServiceIsTransactionP (MQ_CTX const ctx) |
Non-inline replacement for MqServiceIsTransaction … | |
MqContextC - MqContextC_ServiceApi_Service_C_API - overload | |
#define | MqServiceCreate_NULL(...) |
#define | MqServiceCreate(...) |
#define | MqServiceCreate_E(...) |
#define | MqServiceCreate_C(...) |
#define | MqServiceDelete_NULL(...) |
#define | MqServiceDelete(...) |
#define | MqServiceDelete_E(...) |
#define | MqServiceDelete_C(...) |
#define | MqServiceProxy_NULL(...) |
#define | MqServiceProxy(...) |
#define | MqServiceProxy_2(ctx, token) |
#define | MqServiceProxy_E(...) |
#define | MqServiceProxy_C(...) |
#define | MqServiceProxyCtx_NULL(...) |
#define | MqServiceProxyCtx(...) |
#define | MqServiceProxyCtx_E(...) |
#define | MqServiceProxyCtx_C(...) |
#define | MqServiceProxyRoundRobin_NULL(...) |
#define | MqServiceProxyRoundRobin(...) |
#define | MqServiceProxyRoundRobin_E(...) |
#define | MqServiceProxyRoundRobin_C(...) |
#define | MqServiceStorage_NULL(...) |
#define | MqServiceStorage(...) |
#define | MqServiceStorage_E(...) |
#define | MqServiceStorage_C(...) |
MqContextC - create and manage a service …
To provide a service is the main purpose of a server and the main-purpose of a client/server connection is to call a service and to process the result.
A service can be defined on the server or on the client. On the server a service can be initial setup with IServerSetup method and finally cleanup with IServerCleanup.
A service is created with the MqServiceCreate and deleted with the MqServiceDelete.
A service can be created and deleted during the entire life-cycle of the server or the client. If the server/client-context is deleted all services of the are deleted also.
A MqServiceDelete is not required.
Creating or deleting a service is like granting or revoking the right to access a single feature.
eventloop
callback
Example from MyServer.tcl
→ define the service SRV1 on the server-link-setup
package require tclmsgque::MqMsgque namespace import tclmsgque::MqMsgque::* namespace import tclmsgque::MkKernel::* # package-item ::oo::class create MyServer { superclass MqContextC # service to serve all incoming requests for token "HLWO" method myFirstService {} { my SendSTART my SendSTR "[my ReadSTR] World" my SendRETURN } # define a service as link between the token "HLWO" and the callback "MyFirstService" method serverSetup {} { my ServiceCreate "HLWO" myFirstService } # factory startup (constructor) constructor {{tmpl ""}} { next $tmpl my ConfigSetServerSetup serverSetup } } # package-main tclmsgque::MqMsgque Main { # setup commandline arguments for later use set args [MkBufferListC CreateLA {*}$argv] # create "MyServer" factory... and make it to the default. set fct [[MqFactoryC Add MyServer] Default] # inspect commandline-argument for the "factory" to choose... and create a object set fct [MqFactoryC GetCalledL $args] set srv [$fct New] try { $srv LinkCreate $args $srv ProcessEvent MQ_WAIT_FOREVER } on error {} { $srv ErrorCatch } finally { $srv Exit } }
#define MQ_TOK_SIZE (8+1) |
maximum size of the MQ_TOK …
Definition at line 5778 of file LibMqMsgque_mq.h.
#define MqServiceCreate | ( | ... | ) |
Definition at line 720 of file msgque_overload_mq.h.
#define MqServiceCreate_C | ( | ... | ) |
Definition at line 722 of file msgque_overload_mq.h.
#define MqServiceCreate_E | ( | ... | ) |
Definition at line 721 of file msgque_overload_mq.h.
#define MqServiceCreate_NULL | ( | ... | ) |
Definition at line 719 of file msgque_overload_mq.h.
#define MqServiceDelete | ( | ... | ) |
Definition at line 724 of file msgque_overload_mq.h.
#define MqServiceDelete_C | ( | ... | ) |
Definition at line 726 of file msgque_overload_mq.h.
#define MqServiceDelete_E | ( | ... | ) |
Definition at line 725 of file msgque_overload_mq.h.
#define MqServiceDelete_NULL | ( | ... | ) |
Definition at line 723 of file msgque_overload_mq.h.
#define MqServiceProxy | ( | ... | ) |
Definition at line 728 of file msgque_overload_mq.h.
#define MqServiceProxy_2 | ( | ctx, | |
token ) |
Definition at line 729 of file msgque_overload_mq.h.
#define MqServiceProxy_C | ( | ... | ) |
Definition at line 731 of file msgque_overload_mq.h.
#define MqServiceProxy_E | ( | ... | ) |
Definition at line 730 of file msgque_overload_mq.h.
#define MqServiceProxy_NULL | ( | ... | ) |
Definition at line 727 of file msgque_overload_mq.h.
#define MqServiceProxyCtx | ( | ... | ) |
Definition at line 733 of file msgque_overload_mq.h.
#define MqServiceProxyCtx_C | ( | ... | ) |
Definition at line 735 of file msgque_overload_mq.h.
#define MqServiceProxyCtx_E | ( | ... | ) |
Definition at line 734 of file msgque_overload_mq.h.
#define MqServiceProxyCtx_NULL | ( | ... | ) |
Definition at line 732 of file msgque_overload_mq.h.
#define MqServiceProxyRoundRobin | ( | ... | ) |
Definition at line 737 of file msgque_overload_mq.h.
#define MqServiceProxyRoundRobin_C | ( | ... | ) |
Definition at line 739 of file msgque_overload_mq.h.
#define MqServiceProxyRoundRobin_E | ( | ... | ) |
Definition at line 738 of file msgque_overload_mq.h.
#define MqServiceProxyRoundRobin_NULL | ( | ... | ) |
Definition at line 736 of file msgque_overload_mq.h.
#define MqServiceStorage | ( | ... | ) |
Definition at line 741 of file msgque_overload_mq.h.
#define MqServiceStorage_C | ( | ... | ) |
Definition at line 743 of file msgque_overload_mq.h.
#define MqServiceStorage_E | ( | ... | ) |
Definition at line 742 of file msgque_overload_mq.h.
#define MqServiceStorage_NULL | ( | ... | ) |
Definition at line 740 of file msgque_overload_mq.h.
MqContextC - a char[4+1] or hex[8+1] string used to unique identify a service …
A service is defined in pseudocode as:
The token-identifier is defined by the programmer using MqServiceCreate to link a callback with an token-identifier. The token-identifier is part of the MqSendEND, MqSendEND_AND_WAIT, MqSendEND_AND_CALLBACK or MqSendEND_AND_TRANSACTION function-call to identify the service to call.
This is the "traditional" service identifer, the restriction to char[4+1] is used to speedup service lookup by direct mapping of the char[4] string to an MK_I32 integer.
For internal purpose some special token are predefined:
This identifer is used by the rpc feature.
The hex[8+1] is a mapping of the api-function-name to a 32bit hash using the MkSysHashI32 transformed into an
sprintf("%08X")
string.
The goal is to create a unique service identifer atomatically from the already uniqe api-function-name.
Definition at line 5775 of file LibMqMsgque_mq.h.
typedef MqTokenF MqServiceCallbackF |
MqContextC - the callback-function is used as a service-handle or as a event-handle …
A service is using a callback to act on an incoming service-request. The callback is linked to a MqContextC_ServiceApi_Identifer with MqServiceCreate or is used as argument to the MqSendEND_AND_CALLBACK function.
service callbacks are:
Definition at line 5790 of file LibMqMsgque_mq.h.
MQ_EXTERN enum MkErrorE MqServiceCreate_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MqServiceCallbackF const | fCall, | ||
MK_CBP | callback, | ||
MqDataFreeF | fFree, | ||
MkMarkF | fMark ) |
create a link between a service-token and a service-callback …
The servive-token (e.g. MqContextC_ServiceApi_Identifer) have to be unique but the service-callback (e.g. MqServiceCallbackF) not. If a service-callback is not unique than this is called an alias, use string[4] [$ctx ServiceTokenGet]
to get the current token for an incoming-service-call.
The service-callback have to be callable by the server and/or by the child and/or the slave context. A static-callback is a good choice to achive this goal.
The filter, a slave-context, is setup with the initial factory using the initial-class (MqContextC) usually different from the server-class (MyServer…). The filter need the service-callback, usually shared with the server, to report a filter-message to the server.
To distinguish the server and the filter the following functions are used
(all function cann be called as either server or filter context):
ctx.SlaveGet(MASTER)
for the server ctx.SlaveGet(FILTER)
for the filter "if"
clause and the server check"if"
clause and the slave check
Example from Filter6.tcl
→ setup the services for server and filter
method FilterSetup {} { set ftr [my SlaveGetFilter] my variable FH set FH "" my ServiceCreate "LOGF" LOGF my ServiceCreate "EXIT" EXIT my ServiceCreate "SOEX" SOEX my ServiceCreate "ERR1" ERR1 my ServiceStorage "PRNT" my ServiceStorage "PRN2" my ServiceCreate "+ALL" FilterIn $ftr ServiceCreate "WRIT" WRIT my ServiceCreate "WRIT" WRIT $ftr ServiceProxy "WRT2" MASTER }
[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 C-function to process the incoming service-request (C-API only) |
[in] | callback | the user defined callback as data-argument for the C-function fCall |
[in] | fFree | the function to free the data-argument after use (C-API only) |
[in] | fMark | the function to mark the data-argument during garbage-collection (C-API only) |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MqServiceCreate
: callback signatureMQ_EXTERN enum MkErrorE MqServiceDelete_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token ) |
delete a service. …
[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 |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
|
inline |
check if the ongoing-service-call belongs to a transaction …
A service-call can be with-transaction (return true
if the package was send with MqSendEND_AND_WAIT or MqSendEND_AND_CALLBACK) or can be without-transaction (return false
if the package was send with MqSendEND)
[in] | ctx | the MqContextS instance to work on |
true
or false
Definition at line 5800 of file LibMqMsgque_mq.h.
Non-inline replacement for MqServiceIsTransaction …
MQ_EXTERN enum MkErrorE MqServiceProxy_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MQ_SLAVE_ID const | id ) |
create a service to link a master-context with a slave-context. …
This function is used to create a proxy-service to forward the body-data from the read-data-package of the master to the send-data-package of the slave. The data is not changed. This function support the reverse-operation also. If the ctx is a master-context than the data is send to slave identified by id. If the ctx is a slave-context than the data is send to the master of the slave.
[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] | id | the SlaveId to unique identify the master/slave link, the id < MQ_SLAVE_USER is internal. |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MQ_EXTERN enum MkErrorE MqServiceProxyCtx_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MQ_CTX const | target ) |
same as MqServiceProxy but use an MqContextC as input.
MQ_EXTERN bool MqServiceProxyCtxExists | ( | MQ_CTX const | ctx, |
MQ_TOK const | token, | ||
MQ_CTX const | target ) |
check if service who belongs to token is a proxy-service
This is used for route (MqRouteDelete) to identify the service-usage
MQ_EXTERN enum MkErrorE MqServiceProxyRoundRobin_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token, | ||
MK_STRN const | ident ) |
create a proxy-service using Round-Robin as load-balancer …
This function is used to create a proxy-service to forward the body-data from the read-data-package of the master-context to the send-data-package of the slave-context. The data is not changed. This function support the reverse-operation also. If the ctx is a master-context than the data is send to one of the slave-context identified by ident. If the ctx is a slave-context than the data is send to the master-context of the slave.
The Round-Robin-Load-Balancer is only used for the direction from the master-context to the slave-context if the name-resolution return multiple target-context for the single ident.
[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] | ident | the targetIdent used to select a list slave-Context for the Round-Robin |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
MQ_EXTERN enum MkErrorE MqServiceStorage_RT | ( | MK_RT const | mkrt, |
MQ_CTX const | ctx, | ||
MQ_TOK const | token ) |
setup a service listen on a MqContextC_ServiceApi_Identifer and save all read-data-package into the STORAGE …
In a shortterm-transaction-synchronous-service-call the service will return an empty data package. In a longterm-transaction-synchronous-service-call the data will return as normal.
Example from Filter6.tcl
→ using MqServiceStorage to store all packages from service PRNT
and PRN2
into database
method FilterSetup {} { set ftr [my SlaveGetFilter] my variable FH set FH "" my ServiceCreate "LOGF" LOGF my ServiceCreate "EXIT" EXIT my ServiceCreate "SOEX" SOEX my ServiceCreate "ERR1" ERR1 my ServiceStorage "PRNT" my ServiceStorage "PRN2" my ServiceCreate "+ALL" FilterIn $ftr ServiceCreate "WRIT" WRIT my ServiceCreate "WRIT" WRIT $ftr ServiceProxy "WRT2" MASTER }
[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 |
MkExceptionC | → The default-exception from the Programming-Language-Micro-Kernel (PLMK) |
in an ongoing-service-call check if the current MqContextC_ServiceApi_Identifer is token …
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
true
or false
check if the MqContextC_ServiceApi_Identifer token is defined as ctx service …
This code is used to detect if a service with identifer token exists.
[in] | ctx | the MqContextS instance to work on |
[in] | token | the MqContextC SERVICE API to identify the service |
true
or false
in an ongoing-service-call get the current MqContextC_ServiceApi_Identifer …
This function is needed on the server to process a service-request defined as +ALL
or as an alias to extract the current MqContextC_ServiceApi_Identifer.
[in] | ctx | the MqContextS instance to work on |