afs.c File Reference

Macros
#define	NUM_AFS_TABLES   ARRAY_SIZE(afs_tables)
#define	AFS_CLIENT_TIMEOUT   3

Functions
int	send_callback_request (afs_callback *f, struct osl_object *query, callback_result_handler *result_handler, void *private_result_data)
int	send_lls_callback_request (afs_callback *f, const struct lls_command *const cmd, struct lls_parse_result *lpr, void *private_result_data)
int	for_each_matching_row (struct pattern_match_data *pmd)
int	string_compare (const struct osl_object *obj1, const struct osl_object *obj2)
int	afs_cb_result_handler (struct osl_object *result, uint8_t band, void *private)
int	pass_buffer_as_shm (int fd, uint8_t band, const char *buf, size_t size)
__printf_2_3 void	afs_error (const struct afs_callback_arg *aca, const char *fmt,...)
__noreturn void	afs_init (int socket_fd)
__must_check int	afs_event (enum afs_events event, struct para_buffer *pb, void *data)

Variables
int	mmd_mutex
struct misc_meta_data *	mmd
uint32_t	afs_socket_cookie
const struct server_cmd_user_data	lsg_server_cmd_com_select_user_data = { .handler = com_select }
const struct server_cmd_user_data	lsg_server_cmd_com_init_user_data = { .handler = com_init }
const struct server_cmd_user_data	lsg_server_cmd_com_check_user_data = { .handler = com_check }

Detailed Description

The functions of this file execute either in afs or in command handler process context where the afs and the command handler processes are siblings of each other, i.e. direct descendants of the server process. Inter-process communication between command handlers, server and afs is performed through Unix domain sockets.

Macro Definition Documentation

NUM_AFS_TABLES

#define NUM_AFS_TABLES   ARRAY_SIZE(afs_tables)

Used to loop over the afs tables.

AFS_CLIENT_TIMEOUT

#define AFS_CLIENT_TIMEOUT   3

Shutdown connection if query has not arrived until this many seconds.

Function Documentation

send_callback_request()

int send_callback_request	(	afs_callback *	f,
		struct osl_object *	query,
		callback_result_handler *	result_handler,
		void *	private_result_data
	)

Ask the afs process to call a given function.

Parameters

f	The function to be called.
query	Pointer to arbitrary data for the callback.
result_handler	Called for each shm area sent by the callback.
private_result_data	Passed verbatim to result_handler.

This function creates a socket for communication with the afs process and a shared memory area (sma) to which the buffer pointed to by query is copied. It then notifies the afs process that the callback function f should be executed by sending the shared memory identifier (shmid) to the socket.

If the callback produces a result, it sends any number of shared memory identifiers back via the socket. For each such identifier received, result_handler is called. The contents of the sma identified by the received shmid are passed to that function as an osl object. The private_result_data pointer is passed as the second argument to result_handler.

Returns

Number of shared memory areas dispatched on success, negative on errors.

References afs_socket_cookie, ATTACH_RW, connect_local_socket(), OPT_STRING_VAL, recv_bin_buffer(), shm_attach(), shm_detach(), shm_new(), and write_all().

Referenced by send_afs_status().

send_lls_callback_request()

int send_lls_callback_request	(	afs_callback *	f,
		const struct lls_command *const	cmd,
		struct lls_parse_result *	lpr,
		void *	private_result_data
	)

Wrapper for send_callback_request() which passes a lopsub parse result.

Parameters

f	The callback function.
cmd	Needed for (de-)serialization.
lpr	Must match cmd.
private_result_data	Passed to send_callback_request().

This function serializes the parse result given by the lpr pointer into a buffer. The buffer is sent as the query to the afs process with the callback mechanism.

Returns

The return value of the underlying call to send_callback_request().

for_each_matching_row()

int for_each_matching_row

(

struct pattern_match_data *

pmd

)

Execute the given function for each matching row.

Parameters

pmd	Describes what to match and how.

Returns

Standard.

References pattern_match_data::loop_col_num, osl(), pattern_match_data::pm_flags, PM_REVERSE_LOOP, and pattern_match_data::table.

string_compare()

int string_compare	(	const struct osl_object *	obj1,
		const struct osl_object *	obj2
	)

Compare two osl objects of string type.

Parameters

obj1	Pointer to the first object.
obj2	Pointer to the second object.

In any case, only MIN(obj1->size, obj2->size) characters of each string are taken into account.

Returns

It returns an integer less than, equal to, or greater than zero if obj1 is found, respectively, to be less than, to match, or be greater than obj2.

See also

strcmp(3), strncmp(3).

References PARA_MIN.

afs_cb_result_handler()

int afs_cb_result_handler	(	struct osl_object *	result,
		uint8_t	band,
		void *	private
	)

Result handler for sending data to the para_client process.

Parameters

result	The data to be sent.
band	The band designator.
private	Pointer to the command context.

Returns

The return value of the underlying call to command::c::send_sb.

See also

callback_result_handler, command::c::send_sb.

References SBD_CRIT_LOG, SBD_DEBUG_LOG, SBD_EMERG_LOG, SBD_ERROR_LOG, SBD_INFO_LOG, SBD_NOTICE_LOG, SBD_OUTPUT, and SBD_WARNING_LOG.

pass_buffer_as_shm()

int pass_buffer_as_shm	(	int	fd,
		uint8_t	band,
		const char *	buf,
		size_t	size
	)

Send data as shared memory to a file descriptor.

Parameters

fd	File descriptor to send the shmid to.
band	The band designator for this data.
buf	The buffer holding the data to be sent.
size	The size of buf.

This function creates a shared memory area large enough to hold the content given by buf and size and sends the identifier of this area to the file descriptor fd.

It is called by the AFS max_size handler as well as directly by the AFS command callbacks to send command output to the command handlers.

Returns

Zero if buf is NULL or size is zero. Negative on errors, and positive on success.

References ATTACH_RW, PARA_ERROR_LOG, SBD_OUTPUT, shm_attach(), shm_destroy(), shm_detach(), shm_new(), and write_all().

Referenced by afs_error(), and afs_max_size_handler().

afs_error()

__printf_2_3 void afs_error	(	const struct afs_callback_arg *	aca,
		const char *	fmt,
			...
	)

Format and send an error message to the command handler.

To pass an error message from the callback of an afs command to the client, this function should be called. It formats the message into a buffer which is passed as a shared memory area to the command handler from where it propagates to the client.

The message will be tagged with the ERROR_LOG sideband designator so that the client writes it to its stderr stream rather than to stdout as with aca->pbout. In analogy to the default Unix semantics of stderr, the message is sent without buffering.

If sending the error message fails, an error is logged on the server side, but no other action is taken.

Parameters

aca	Used to obtain the fd to send the shmid to.
fmt	Usual format string.

References afs_callback_arg::fd, PARA_ERROR_LOG, para_strerror(), pass_buffer_as_shm(), SBD_ERROR_LOG, and xvasprintf().

afs_init()

__noreturn void afs_init

(

int

socket_fd

)

Initialize the audio file selector.

Parameters

socket_fd

File descriptor for communication with the server process.

Open all tables of the afs database, then schedule the signal task and the command task. The former reacts to signals by reloading the database or by terminating after closing all database tables. The command task dispatches commands from the server and from command handlers.

The server connects the command task when the virtual streaming system needs to stream the next audio file. The command task opens the highest scoring admissible file and sends streaming information back to the server. The command task also accepts connections from command handlers, modifies or queries the afs database accordingly, and reports its findings back to the command handler.

afs_event()

__must_check int afs_event	(	enum afs_events	event,
		struct para_buffer *	pb,
		void *	data
	)

The afs event dispatcher.

Parameters

event	Type of the event.
pb	May be NULL.
data	Type depends on event.

This function calls each table event handler, passing pb and data verbatim. It's up to the handlers to interpret the data pointer. If a handler returns negative, the loop is aborted.

Returns

The (negative) error code of the first handler that failed, or non-negative if all handlers succeeded.

References NUM_AFS_TABLES.

Variable Documentation

mmd_mutex

int mmd_mutex

extern

The mutex protecting the shared memory area containing the mmd struct.

mmd

struct misc_meta_data* mmd

extern

Pointer to shared memory area for communication between para_server and its children.

Exported to vss.c, command.c and to afs.

afs_socket_cookie

uint32_t afs_socket_cookie

extern

A random number used to "authenticate" the afs connection.

para_server picks this number by random before it forks the afs process. The command handlers know this number as well and write it to the afs socket, together with the id of the shared memory area which contains the payload of the afs command. A local process has to know this number to abuse the afs service provided by the local socket.

Referenced by send_callback_request().

lsg_server_cmd_com_select_user_data

const struct server_cmd_user_data lsg_server_cmd_com_select_user_data = { .handler = com_select }

lsg_server_cmd_com_init_user_data

const struct server_cmd_user_data lsg_server_cmd_com_init_user_data = { .handler = com_init }

lsg_server_cmd_com_check_user_data

const struct server_cmd_user_data lsg_server_cmd_com_check_user_data = { .handler = com_check }