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. More...

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. More...

int	et_system_config_setevents (et_sysconfig sconfig, int val)
	This routine sets the configuration's total number of events. More...

int	et_system_config_getevents (et_sysconfig sconfig, int *val)
	This routine gets the configuration's total number of events. More...

int	et_system_config_setsize (et_sysconfig sconfig, size_t val)
	This routine sets the configuration's event size in bytes. More...

int	et_system_config_getsize (et_sysconfig sconfig, size_t *val)
	This routine gets the configuration's event size in bytes. More...

int	et_system_config_settemps (et_sysconfig sconfig, int val)
	This routine sets the configuration's maximum number of temporary events. More...

int	et_system_config_gettemps (et_sysconfig sconfig, int *val)
	This routine gets the configuration's maximum number of temporary events. More...

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). More...

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). More...

int	et_system_config_setprocs (et_sysconfig sconfig, int val)
	This routine sets the configuration's maximum number of processes that may be created. More...

int	et_system_config_getprocs (et_sysconfig sconfig, int *val)
	This routine gets the configuration's maximum number of processes that may be created. More...

int	et_system_config_setattachments (et_sysconfig sconfig, int val)
	This routine sets the configuration's maximum number of attachments that may be created. More...

int	et_system_config_getattachments (et_sysconfig sconfig, int *val)
	This routine gets the configuration's maximum number of attachments that may be created. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

int	et_system_config_setfile (et_sysconfig sconfig, const char *val)
	This routine sets the configuration's ET system file name. More...

int	et_system_config_getfile (et_sysconfig sconfig, char *val)
	This routine gets the configuration's ET system file name. More...

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_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_UDP_PORT, 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.

Functions

Detailed Description

Function Documentation