child

Definition

`context`	the real application using the libFreiburg 2.0 interface and service handles
`client`	the part of the software doing the connect system-call
`server`	the part of the software doing the accept system-call (e.g. service)
`parent`	the first context of a client / server pair
`child`	the second or more context of the parent - client / server pair

Context

the context is libFreiburg 2.0 plus a collection of service handles.
both client and server are able to create multiple parent and child context.

every client is able to create additional server-parent context and every server is able to create additional client-parent context.

                       *- client21 -> server21
         |-> server11 -*
         |             *- client22 -> server22
client1 -|
         |             *- client23 -> server23
         |-> server12 -*
                       *- client24 -> server24

every context on the client has a link to a context on the server.
every context is able to provide different service handles.
every handle is recognized by a 4 character token and have to be unique per context.

a handle can be dynamically added or removed.
using 'C' code

struct MqTokenS * const srvT = msgque->srvT;            // get the 'srvT' member of the MqS object
MqErrorCheck(MqTokenAddHdl(srvT, "TOK2", proc2, data2); // add TOK2 as service handle
MqErrorCheck(MqTokenDelHdl(srvT, "TOK2");               // delete TOK2 as service handle

using 'Tcl' code

$Ctx service create TOK2 tclProc2;	## add TOK2 as service handle
$Ctx service delete TOK2;		## delete TOK2 as service handle

the service handle is needed to supply a 'service' usable by a remote context
using 'C' code

static MqErrorE pMYDO(MqSP const msgque, MQ_PTR data) {
  MqReadSP const read = msgque->read;
  MqSendSP const send = msgque->send;
  MqBufferSP buf;                           // buffer space
  MqErrorCheck (MqReadU (read, &buf));      // read next item into buffer object
  MqSendSTART (send);                       // reset the send object
  MqSendC (send,pDoSomeUsefullThings(buf)); // append string item
  return MqSendEND_RETR (send,NULL);        // send answer back
error:                                      // used by MqErrorCheck
  return MqSendRETURN(send,MQ_ERROR_PROC_FMT,__func__);
}
// read command-line: -name Ars -tcp -inetd -host arsHost -port arsservice
MqBufferLSP argv = MqBufferLCreateArgv(NULL, --argc, ++argv);
MqBufferLAppendH2(argv, "-type", MQ_CLIENT);                // using 'client' behavior
MqErrorCheck(MqCreate(context, argv, &context->msgque));    // create the 'Freiburg' object
MqTokenSP const token = context->msgque->srvT;              // get the 'service' token
MqErrorCheck(MqTokenAddHdl(token, "MYDO", pMYDO, NULL));    // set the 'MYDO' service handle

using 'Tcl' code

set Ctx [tclFreiburg::Start -name Ars -tcp -inetd -host arsHost -port arsservice]
proc ProvideSomeData {Ctx} {
    $Ctx send -retcode ok MYD0 [DoSomeUsefullThings [$Ctx read next]]
}
$Ctx service create MYD0 ProvideSomeData;

client

every new client-parent-context start a new server and creating a server-parent-context
using 'C' code

// read command-line: -name MyApplication
MqBufferLSP argv = MqBufferLCreateArgv(NULL, --argc, ++argv);
MqBufferLAppendH2(argv, "-type", MQ_CLIENT);                // using 'client' behavior
MqErrorCheck(MqCreate(context, argv, &context->msgque));    // create the 'Freiburg' object

using 'Tcl' code

set Ctx [tclFreiburg::Start -name MyApplication];

every deletion of the client-parent-context stop the previous started server
using 'C' code
```
MqDelete(&context->msgque);
```
using 'Tcl' code
```
rename $CTX "";
```
every client can have multiple parent-context there is a n:1 relationship between client and server (e.g. one client has multiple server and one server has one client ) in local mode the client start and connect to the server as -uds or -tcp without using the -inetd behaviour
```
set Ctx [tclFreiburg::Start -name MyApplication -uds];  # using '-uds' communication
set Ctx [tclFreiburg::Start -name MyApplication -tcp];  # using '-tcp' communication
```
in remote mode the client connect to the server as -tcp or -uds using the -inetd behaviour
```
set Ctx [tclFreiburg::Start -name MyApplication -tcp -inetd -host myHost -port myPort];
```
the client gets all the error/warning/info messages from the server

libFreiburg 2.0 startup options:

option	type	default	description
-name	STR	"noname"	the name of the application
-type	INT	MQ_CLIENT	MqE type of the application
-debug	INT	0	debug level (0-9)
-stat	INT	0	statistics level (0-9)
-parent	ID	NULL	create as CHILD of parent
-string	BOOL	no	convert every non-binary MqTypeE data to string
-silent	BOOL	no	be silent?
-inetd	BOOL	no	remote mode: using inetd to start the server?
-timeout	INT	system	timeout seconds to wait for connection
-server	STR	NULL	local mode: path to the server
-uds	BOOL	yes	use UDS style communication?
-file	STR	random	UDS file name
-tcp	BOOL	no	use TCP style communication?
-host	STR	localhost	server TCP host-name
-port	STR	random	server TCP port as number or string
-myhost	STR	NULL	client TCP host-name
-myport	STR	NULL	client TCP port as number or string
-fCreate	POINTER	NULL	the `ContextCreate` procedure
-fDelete	POINTER	NULL	the `ContextDelete` procedure
-fevent	POINTER	NULL	procedure to call external event-queue
-id	STRING	INTERNAL	local mode: used for internal purpose

server

in general the server is started and controlled by the client

in local mode the server is started by the client with the system command (e.g. using the PATH environment variable)
```
tclFreiburg::Start -name Ars -uds -server ArsService.exe
```

in remote mode the server is started by inetd

Example: /etc/services

arsservice      16790/tcp       # ARS application server as 'Freiburg' service

Example: /etc/inetd.conf

arsservice stream tcp nowait arsuser /path/to/the/ArsService.exe ArsService -inetd -tcp

Parent

the parent is the first context created
every new parent-context on the client connect to a new server using a new parent-context

every parent-context on the client has an according parent-context on the server

ArsServer1                   ArsServer2
    |                            |
ArsService(local)            ArsService(arsHost:arsPort)
    |                            |
    |Parent1              Parent2|
    ^--------tclFreiburg---------^

the parent control the socket communication interface
- the client-parent-context is doing the connect system-call
- the server-parent-context is doing the accept system-call

a context is a parent-context if no -parent option is available

Example: a parent on a local host

 set Parent1 [tclFreiburg::Start -name Ars -uds];

Example: a parent on a network reachable host

 set Parent2 [tclFreiburg::Start -name Ars -tcp -inetd -host arsHost -port arsPort];

Child

the child is the second or more context created
every new child-context on the client is creating a new child-context on a already started server

every child-context on the client has an according child-context on the server

ArsServer1                   ArsServer2
    |                            |
    ^---------ArsService---------^
           <-- |      | -->
             parent child
               |      |
             tclFreiburg

a context is a child-context if the -parent option is available

the child-context inherits binary, debug, statistic and silent option from the parent-context on the server
using 'Tcl' code

set Ctx [tclFreiburg::Start -name Ars -uds];   # I'm a parent
set Cl1 [tclFreiburg::Start -parent $Ctx];     # I'm a child
set Cl2 [tclFreiburg::Start -parent $Ctx];     # I'm an other child
set Cl3 [tclFreiburg::Start -parent $Cl1];     # I'm an other child, even if my '-parent' is a child

the child-context is using the parent-context for socket communication
if a parent-context will be deleted the child-context will be deleted too

prev: Installation - top: libFreiburg 2.0 - next: create a snmp service

Generated on Tue Nov 23 16:13:06 2004 for libFreiburg by

1.3.8-20040928