System config
[Developer routines]

These routines are for configuring an ET system. More...

Functions

int et_system_config_init (et_sysconfig *sconfig)
 This routine initializes a configuration used to define an ET system.
int et_system_config_destroy (et_sysconfig sconfig)
 This routine frees the memory allocated when a system configuration is initialized by et_system_config_init.
int et_system_config_setevents (et_sysconfig sconfig, int val)
 This routine sets the configuration's total number of events.
int et_system_config_getevents (et_sysconfig sconfig, int *val)
 This routine gets the configuration's total number of events.
int et_system_config_setsize (et_sysconfig sconfig, size_t val)
 This routine sets the configuration's event size in bytes.
int et_system_config_getsize (et_sysconfig sconfig, size_t *val)
 This routine gets the configuration's event size in bytes.
int et_system_config_settemps (et_sysconfig sconfig, int val)
 This routine sets the configuration's maximum number of temporary events.
int et_system_config_gettemps (et_sysconfig sconfig, int *val)
 This routine gets the configuration's maximum number of temporary events.
int et_system_config_setstations (et_sysconfig sconfig, int val)
 This routine sets the configuration's maximum number of stations that may be created (including GRAND_CENTRAL).
int et_system_config_getstations (et_sysconfig sconfig, int *val)
 This routine gets the configuration's maximum number of stations that may be created (including GRAND_CENTRAL).
int et_system_config_setprocs (et_sysconfig sconfig, int val)
 This routine sets the configuration's maximum number of processes that may be created.
int et_system_config_getprocs (et_sysconfig sconfig, int *val)
 This routine gets the configuration's maximum number of processes that may be created.
int et_system_config_setattachments (et_sysconfig sconfig, int val)
 This routine sets the configuration's maximum number of attachments that may be created.
int et_system_config_getattachments (et_sysconfig sconfig, int *val)
 This routine gets the configuration's maximum number of attachments that may be created.
int et_system_config_setport (et_sysconfig sconfig, int val)
 This routine sets the configuration's UDP listening port used by remote users trying to find the ET system by broad/multicasting.
int et_system_config_getport (et_sysconfig sconfig, int *val)
 This routine gets the configuration's UDP listening port used by remote users trying to find the ET system by broad/multicasting.
int et_system_config_setserverport (et_sysconfig sconfig, int val)
 This routine sets the configuration's TCP listening port number used to communicate with remote users.
int et_system_config_getserverport (et_sysconfig sconfig, int *val)
 This routine gets the configuration's TCP listening port number used to communicate with remote users.
int et_system_config_setgroups (et_sysconfig sconfig, int groups[], int size)
 This routine sets the configuration's number of event groups and how many events are in each group.
int et_system_config_settcp (et_sysconfig sconfig, int rBufSize, int sBufSize, int noDelay)
 This routine sets the configuration's TCP socket options used when communicating with remote users over sockets.
int et_system_config_gettcp (et_sysconfig sconfig, int *rBufSize, int *sBufSize, int *noDelay)
 This routine gets the configuration's TCP socket options used when communicating with remote users over sockets.
int et_system_config_addmulticast (et_sysconfig sconfig, const char *val)
 This routine 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.
int et_system_config_removemulticast (et_sysconfig sconfig, const char *val)
 This routine removes a multicast address from a list, so that the ET system no longer listens on it for UDP packets from users trying to find the system.
int et_system_config_setfile (et_sysconfig sconfig, const char *val)
 This routine sets the configuration's ET system file name.
int et_system_config_getfile (et_sysconfig sconfig, char *val)
 This routine gets the configuration's ET system file name.

Detailed Description

These routines are for configuring an ET system.


Function Documentation

int et_system_config_addmulticast ( et_sysconfig  sconfig,
const char *  val 
)

This routine 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.

No more than ET_MAXADDRESSES number of multicast addresses can be added. Duplicate entries are not added to the list.

Parameters:
sconfig system configuration.
val multicast address in dot-decimal form.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is NULL or is not in valid dot-decimal form; if ET_MAXADDRESSES number of multicast addresses have already been added.

References ET_ERROR, ET_IPADDRSTRLEN, ET_MAXADDRESSES, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::mcastaddrs.

int et_system_config_destroy ( et_sysconfig  sconfig  ) 

This routine frees the memory allocated when a system configuration is initialized by et_system_config_init.

Parameters:
sconfig system configuration.
Returns:
ET_OK.

References ET_OK.

int et_system_config_getattachments ( et_sysconfig  sconfig,
int *  val 
)

This routine gets the configuration's maximum number of attachments that may be created.

Parameters:
sconfig system configuration.
val int pointer which gets filled with the maximum number of attachments.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.
See also:
et_system_config_setattachments.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::nattachments.

int et_system_config_getevents ( et_sysconfig  sconfig,
int *  val 
)

This routine gets the configuration's total number of events.

Parameters:
sconfig system configuration.
val int pointer which gets filled with number of events.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::nevents.

int et_system_config_getfile ( et_sysconfig  sconfig,
char *  val 
)

This routine gets the configuration's ET system file name.

Parameters:
sconfig system configuration.
val pointer which gets filled with the ET file name.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.
See also:
et_system_config_setfile.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::filename, and et_sys_config_t::init.

int et_system_config_getport ( et_sysconfig  sconfig,
int *  val 
)

This routine gets the configuration's UDP listening port used by remote users trying to find the ET system by broad/multicasting.

Parameters:
sconfig system configuration.
val int pointer which gets filled with the UDP listening port.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.
See also:
et_system_config_setport.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::port.

int et_system_config_getprocs ( et_sysconfig  sconfig,
int *  val 
)

This routine gets the configuration's maximum number of processes that may be created.

Parameters:
sconfig system configuration.
val int pointer which gets filled with the maximum number of processes.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.
See also:
et_system_config_setprocs.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::nprocesses.

int et_system_config_getserverport ( et_sysconfig  sconfig,
int *  val 
)

This routine gets the configuration's TCP listening port number used to communicate with remote users.

Parameters:
sconfig system configuration.
val int pointer which gets filled with the TCP listening port.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.
See also:
et_system_config_setserverport.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::serverport.

int et_system_config_getsize ( et_sysconfig  sconfig,
size_t *  val 
)

This routine gets the configuration's event size in bytes.

Parameters:
sconfig system configuration.
val pointer which gets filled with event size in bytes.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::event_size, and et_sys_config_t::init.

int et_system_config_getstations ( et_sysconfig  sconfig,
int *  val 
)

This routine gets the configuration's maximum number of stations that may be created (including GRAND_CENTRAL).

Parameters:
sconfig system configuration.
val int pointer which gets filled with the maximum number of stations.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::nstations.

int et_system_config_gettcp ( et_sysconfig  sconfig,
int *  rBufSize,
int *  sBufSize,
int *  noDelay 
)

This routine gets the configuration's TCP socket options used when communicating with remote users over sockets.

Parameters:
sconfig system configuration.
rBufSize int pointer which gets filled with the TCP socket receive buffer size in bytes.
sBufSize int pointer which gets filled with the TCP socket send buffer size in bytes.
noDelay int pointer which gets filled with 1 if TCP_NODELAY option is set, else 0.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized.
See also:
et_system_config_settcp.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, et_sys_config_t::tcpNoDelay, et_sys_config_t::tcpRecvBufSize, and et_sys_config_t::tcpSendBufSize.

int et_system_config_gettemps ( et_sysconfig  sconfig,
int *  val 
)

This routine gets the configuration's maximum number of temporary events.

Parameters:
sconfig system configuration.
val int pointer which gets filled with the maximum number of temporary events.
Returns:
ET_OK if successful.
ET_ERROR if either arg is NULL or sconfig not initialized.
See also:
et_system_config_settemps.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::ntemps.

int et_system_config_init ( et_sysconfig sconfig  ) 

This routine initializes a configuration used to define an ET system.

This MUST be done prior to setting any configuration parameters or all setting routines will return an error.

Parameters:
sconfig pointer to system configuration variable.
Returns:
ET_OK if successful.
ET_ERROR if arg is NULL or failure to allocate memory for configuration data storage.
ET_ERROR_NOMEM if there is not enough memory allocated to store network info. Recompile code with bigger value of ET_MAXADDRESSES.

References et_sys_config_t::bcastaddrs, ET_ATTACHMENTS_MAX, ET_BROADCAST_PORT, ET_ERROR, ET_ERROR_NOMEM, ET_EVENT_GROUPS_MAX, ET_MAXADDRESSES, ET_OK, ET_PROCESSES_MAX, ET_SERVER_PORT, ET_STRUCT_OK, ET_SYSTEM_ESIZE, ET_SYSTEM_EVENTS, ET_SYSTEM_NSTATS, ET_SYSTEM_NTEMPS, et_sys_config_t::event_size, et_sys_config_t::filename, et_sys_config_t::groupCount, et_sys_config_t::groups, et_sys_config_t::init, et_sys_config_t::mcastaddrs, et_sys_config_t::nattachments, et_sys_config_t::netinfo, et_sys_config_t::nevents, et_sys_config_t::nprocesses, et_sys_config_t::nstations, et_sys_config_t::ntemps, et_sys_config_t::port, et_sys_config_t::serverport, et_sys_config_t::tcpNoDelay, et_sys_config_t::tcpRecvBufSize, and et_sys_config_t::tcpSendBufSize.

int et_system_config_removemulticast ( et_sysconfig  sconfig,
const char *  val 
)

This routine removes a multicast address from a list, so that the ET system no longer listens on it for UDP packets from users trying to find the system.

Parameters:
sconfig system configuration.
val multicast address in dot-decimal form.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is NULL or is not in valid dot-decimal form.
See also:
et_system_config_addmulticast.

References ET_ERROR, ET_IPADDRSTRLEN, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::mcastaddrs.

int et_system_config_setattachments ( et_sysconfig  sconfig,
int  val 
)

This routine sets the configuration's maximum number of attachments that may be created.

The number of attachments is the number of local et_station_attach calls successfully returned - each providing an access to events from a certain station. This routine sets the limit, but is capped at ET_ATTACHMENTS_MAX which may be changed in et_private.h, requiring a recompile of the ET system library.

Parameters:
sconfig system configuration.
val any positive integer, if > ET_ATTACHMENTS_MAX, then it is set to ET_ATTACHMENTS_MAX.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is < 1.

References ET_ATTACHMENTS_MAX, ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::nattachments.

int et_system_config_setevents ( et_sysconfig  sconfig,
int  val 
)

This routine sets the configuration's total number of events.

Parameters:
sconfig system configuration.
val any positive integer.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is < 1.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::groupCount, et_sys_config_t::groups, et_sys_config_t::init, et_sys_config_t::nevents, and et_sys_config_t::ntemps.

int et_system_config_setfile ( et_sysconfig  sconfig,
const char *  val 
)

This routine sets the configuration's ET system file name.

The name can be no longer than (ET_FILENAME_LENGTH - 1) characters in length.

Parameters:
sconfig system configuration.
val ET system file name.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is NULL or > (ET_FILENAME_LENGTH - 1) chars.

References ET_ERROR, ET_FILENAME_LENGTH, ET_OK, ET_STRUCT_OK, et_sys_config_t::filename, and et_sys_config_t::init.

int et_system_config_setgroups ( et_sysconfig  sconfig,
int  groups[],
int  size 
)

This routine sets the configuration's number of event groups and how many events are in each group.

To prevent ET clients who grab new events from competing with each other for these new events, an ET system can divide events into groups. The given array specifies how many events are in each group. Groups are numbered sequentially from 1 (corresponding to the element group[0]). Clients may either call et_system_setgroup to specify which group to get events from when calling et_events_new, or clients may call et_events_new_group to obtain new events from a specific group regardless of any default group set by et_system_setgroup.

Parameters:
sconfig system configuration.
groups array containing the number of events in each group. The index into the array plus one gives the group number. The first size number of elements must be positive integers. The sum of the first size elements must equal the total number of events in the system.
size number of array elements in group to be used.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if groups == NULL or element of group < 1; if size > ET_EVENT_GROUPS_MAX or < 1.

References ET_ERROR, ET_EVENT_GROUPS_MAX, ET_OK, ET_STRUCT_OK, et_sys_config_t::groupCount, et_sys_config_t::groups, and et_sys_config_t::init.

int et_system_config_setport ( et_sysconfig  sconfig,
int  val 
)

This routine sets the configuration's UDP listening port used by remote users trying to find the ET system by broad/multicasting.

Parameters:
sconfig system configuration.
val port number of the broadcast or multicast communications. The default is ET_BROADCAST_PORT, defined in et.h. It may also be set to any available port number.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val < 1024 or > 65535.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::port.

int et_system_config_setprocs ( et_sysconfig  sconfig,
int  val 
)

This routine sets the configuration's maximum number of processes that may be created.

The number of processes is just the number of et_open calls successfully returned on the same host as the ET system. The system must be one which can allow many processes to share the ET mutexes, thus allowing full access to the shared memory. On MacOS this is not possible, meaning that the local user does NOT have the complete access to the shared memory. This routine sets the limit, but is capped at ET_PROCESSES_MAX which may be changed in et_private.h, requiring a recompile of the ET system library.

Parameters:
sconfig system configuration.
val any positive integer, if > ET_PROCESSES_MAX, then it is set to ET_PROCESSES_MAX.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is < 1.

References ET_ERROR, ET_OK, ET_PROCESSES_MAX, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::nprocesses.

int et_system_config_setserverport ( et_sysconfig  sconfig,
int  val 
)

This routine sets the configuration's TCP listening port number used to communicate with remote users.

If not set here, the port defaults to ET_SERVER_PORT (defined in et.h). The ET system process exits with an error if the port is not available.

Parameters:
sconfig system configuration.
val port number of the TCP communications which may be set to any available port number.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val < 1024 or > 65535.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::serverport.

int et_system_config_setsize ( et_sysconfig  sconfig,
size_t  val 
)

This routine sets the configuration's event size in bytes.

Parameters:
sconfig system configuration.
val any positive integer within the bounds of available memory.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is < 1.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::event_size, and et_sys_config_t::init.

int et_system_config_setstations ( et_sysconfig  sconfig,
int  val 
)

This routine sets the configuration's maximum number of stations that may be created (including GRAND_CENTRAL).

Parameters:
sconfig system configuration.
val any positive integer.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is < 1.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, and et_sys_config_t::nstations.

int et_system_config_settcp ( et_sysconfig  sconfig,
int  rBufSize,
int  sBufSize,
int  noDelay 
)

This routine sets the configuration's TCP socket options used when communicating with remote users over sockets.

The receive and send buffer sizes in bytes and the TCP_NODELAY values can be set. If a buffer size is set to 0, the operating system default is used.

Parameters:
sconfig system configuration.
rBufSize TCP socket receive buffer size in bytes.
sBufSize TCP socket send buffer size in bytes.
noDelay if 0, TCP_NODELAY option is not set, else it is.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if a buffer size < 0.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, et_sys_config_t::tcpNoDelay, et_sys_config_t::tcpRecvBufSize, and et_sys_config_t::tcpSendBufSize.

int et_system_config_settemps ( et_sysconfig  sconfig,
int  val 
)

This routine sets the configuration's maximum number of temporary events.

The max number of temp events must not be greater than the total number of events. Temp events are created when a user calls et_events_new() with a larger memory size than the normal events created in the main shared memory. Their creation is expensive and the ET system operates much faster by increasing the size of normal events in order to avoid creating any temp events at all.

Parameters:
sconfig system configuration.
val any positive integer <= total number of events.
Returns:
ET_OK if successful.
ET_ERROR if sconfig is NULL or not initialized; if val is < 1 or > total number of events.

References ET_ERROR, ET_OK, ET_STRUCT_OK, et_sys_config_t::init, et_sys_config_t::nevents, and et_sys_config_t::ntemps.


Generated on 30 Jul 2015 for ET System by  doxygen 1.6.1