Creating an ET
system
System
Creation
To create an new ET system one only needs to make a single call to the ET library function, et_system_start. All ET systems are completely independent of each other, allowing the creation of as many as are necessary. However, bear in mind that the process creating an ET system must remain in existence. In other words, it does NOT spawn or fork off an independent ET process (although it is possible for any user to implement such behavior).
The arguments to et_system_start(et_sys_id* id, et_sysconfig sconfig) are a pointer to an ET system identification and an ET system configuration.
The behavior of this routine is as follows. If the name of the ET system file (see below) given in the configuration parameter does not exist, an ET system is created with no objections. If, however, such a file does exist, it is first mapped into the process' memory. The memory is monitored to see if there is a living system heartbeat. If there is, then an ET system is already attached to it and an error is returned. If there isn't, the file is deleted before creating a new ET system.
To close the newly created ET system, use the function et_system_close(et_sys_id id). This may only be called by the process which called et_system_start or an error will be returned.
ET system
identification
An ET system id is created by declaring a variable of the type et_sys_id. A pointer to this variable is then passed to et_system_start. When the user has no more use for the ET system, a call to et_system_close will stop all ET-related threads and unmap the ET memory. The process that called et_system_start can continue on its merry way, but all ET consumers are left to fend for themselves.
Alternatively, if a user is attaching to an existing ET system instead of trying to create one, a pointer to a system id is one parameter passed to the et_open function (more on this later). A call to et_close is then required to cleanly remove the connection to the ET system.
ET system
configuration
An ET system configuration is created by declaring a variable of the type et_sysconfig. Once this variable is declared, it must be initialized before further use. Thus users must call the function et_system_config_init. After initialization, calls can be made to functions which set various properties of the specific configuration. Calls to these setting functions will fail unless the configuration is first initialized.
When the user is finished using a configuration variable, the user must call et_system_config_destroy with the configuration as an argument in order to properly release all memory used.
The configuration parameters that the user can set are the total number of events, the maximum size of each event, the maximum number of temporary events, the maximum number of stations, the maximum number of connecting processes, the maximum number of attachments to stations, and the name of the system. For remote users, one can set how to find the ET systems, what IP addresses to use, and what port numbers to use.
The functions used to SET these parameters are listed below along with a short explanation for each:
1. et_system_config_setevents(et_sysconfig sconfig, int val) : sets the total number of
events.
2. et_system_config_setsize(et_sysconfig sconfig, int val) : sets the maximum size in
bytes for each events' data.
3. et_system_config_settemps(et_sysconfig sconfig, int val) : sets the maximum number of
temporary events. These events are used when an event is required whose data
size exceeds the limit set by the previous function. To accommodate large
events, memory is specially allocated as needed. This cannot exceed the total
number of events in the system.
4. et_system_config_setstations(et_sysconfig sconfig, int val) : sets the maximum number of
stations.
5. et_system_config_setprocs(et_sysconfig sconfig, int val) : sets the maximum number of
user processes which may open an ET system.
6. et_system_config_setattachments(et_sysconfig sconfig, int val) : sets the maximum number of
attachments to stations.
7. et_system_config_setfile(et_sysconfig sconfig, char *val)
: defines the name of an ET system. Each ET system is defined by a unique file
name which is used to implement the memory mapped file basis of the ET system.
8. et_system_config_addmulticast(et_sysconfig sconfig, char *val)
: adds a multicast address to a list, each address of which the ET system
is listening on for UDP packets from users trying to find it. The address must
be in dotted-decimal form.
9. et_system_config_removemulticast(et_sysconfig sconfig, char *val)
: removes a multicast address from a list of addresses the ET system is
listening on for UDP packets from users trying to find it. The address must be
in dotted-decimal form.
10. DEPRECATED et_system_config_setcast(et_sysconfig sconfig, int val) : no longer does anything
but is included for backwards compatibility.
11. DEPRECATED et_system_config_setaddress(et_sysconfig sconfig, char *val)
: this routine is replaced by et_system_config_addmulticast,
but is included for backwards compatibility. Currently it adds a multicast
address to the appropriate list, each address of which the ET system is
listening on for UDP packets from users trying to find it. The address must be
in dotted-decimal form.
12. et_system_config_setport(et_sysconfig sconfig, int val) : for remote users, set the
broad/multicast port number.
13. et_system_config_setgroups(et_sysconfig sconfig, int groups[], int size) : set the number of groups
into which events are divided and the number of events in each group. There are
situations in which several producers need to grab and fill new events. In
order to prevent a single producer from grabbing too many events and slowing
down or stopping other producers, events may be divided into groups. The
“groups” arg is an array in which the
index is the group number and the value is the number of events in the group.
All non-zero values must be contiguous and start at index 0. The
“size” arg is the size of the array.
Events of a certain group number can be retrieved with et_events_new_group.
Similarly, functions used to GET these parameters are available and listed in the chapter describing all the ET library routines.
Example
An example of a program to start an ET system is listed below. The reader can also take a look at et_start.c from which the program below is derived.
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <string.h>
#include <et.h>
main(int argc, char
**argv)
{
int status, sig_num;
sigset_t sigwaitset;
et_sysconfig config;
et_sys_id id;
if (argc != 2) {
printf("Usage: et_start
<name>\n");
exit(1);
}
/********************************/
/* set configuration parameters */
/********************************/
if (et_system_config_init(&config) == ET_ERROR) {
printf("et_start:
no more memory\n");
exit(1);
}
/* total number of events */
et_system_config_setevents(config, 1000);
/* size of event in bytes */
et_system_config_setsize(config, 2000);
/* max number of temporary (specially allocated mem)
events */
/* This cannot exceed total # of events */
et_system_config_settemps(config, 500);
/* soft limit on number of stations (hard limit = ET_SYSTEM_NSTATS) */
et_system_config_setstations(config, 10);
/* soft limit on number of attachments (hard limit = ET_ATTACHMENTS_MAX)
*/
et_system_config_setattachments(config, 10);
/* soft limit on number of processes (hard limit = ET_PROCESSES_MAX) */
et_system_config_setprocs(config, 10);
/* set UDP port */
et_system_config_setport(config, 12222);
/* respond to multicasts at this address */
et_system_config_addmulticast(config, "239.200.35.7");
/* set ET system filename */
if (et_system_config_setfile(config,argv[1]) == ET_ERROR) {
printf("et_start:
bad filename argument\n");
exit(1);
};
/*************************/
/* start ET system */
/*************************/
printf("et_start:
starting ET system %s\n", argv[1]);
if (et_system_start(&id, config) != ET_OK) {
printf("et_start:
error in starting ET system\n");
exit(1);
}
/* set level of debug output */
et_system_setdebug(id,
ET_DEBUG_INFO);
/* turn this thread into a signal handler */
sigemptyset(&sigwaitset);
sigaddset(&sigwaitset,
SIGINT);
sigwait(&sigwaitset,
&sig_num);
printf("I got
CONTROL-C\n");
exit(0);
}
