The server connection collection. More...

#include "common.h"
#include "pqs.h"

Functions
bool	pqs_connections_active (size_t index)
	Check if a collection member is set to active.

pqs_connection_state *	pqs_connections_add (void)
	Add an item to the connection collection and set it to active.

size_t	pqs_connections_available (void)
	Get the number of available (inactive) connection states in the collection.

pqs_connection_state *	pqs_connections_get (uint32_t instance)
	Get a connection state pointer from a given instance number.

void	pqs_connections_initialize (size_t count, size_t maximum)
	Initialize the connection collection.

void	pqs_connections_clear (void)
	Erase (clear) all the connection collection members.

void	pqs_connections_dispose (void)
	Dispose of the connection collection state.

pqs_connection_state *	pqs_connections_index (size_t index)
	Get a connection state pointer by its collection index.

bool	pqs_connections_full (void)
	Check if the connection collection is full.

pqs_connection_state *	pqs_connections_next (void)
	Get the next available connection state.

void	pqs_connections_reset (uint32_t instance)
	Reset a connection in the collection.

size_t	pqs_connections_size (void)
	Get the total number of connection state items in the collection.

void	pqs_connections_self_test (void)
	Run the self-test for the connection collection.

Detailed Description

The server connection collection.

This header defines a collection of functions for managing the server connection states in the PQS implementation. These functions are internal (non-exportable) and are used to maintain an array (or collection) of connection state objects. The functions allow for initialization, addition, retrieval, reset, and disposal of connection states, as well as performing a self-test of the collection functionality.

The collection is implemented as a dynamically allocated array of connection state structures along with a parallel array of booleans to indicate which entries are active.

Function Documentation

◆ pqs_connections_active()

bool pqs_connections_active ( size_t index )

Check if a collection member is set to active.

This function checks if the connection state at the given index in the collection is marked as active. If the index is within bounds, the function returns the boolean flag from the internal active array. Otherwise, it returns false.

Parameters

index The socket index number within the collection.

Returns: Returns true if the connection at the specified index is active; otherwise, false.

◆ pqs_connections_add()

pqs_connection_state * pqs_connections_add ( void )

Add an item to the connection collection and set it to active.

This function adds a new connection state to the collection if the current number of entries plus one does not exceed the maximum allowed. It reallocates the internal arrays as needed, initializes the new connection state, sets its connection identifier (cid) to its index, and marks it as active.

Returns: Returns a pointer to the new connection state item or NULL if the maximum capacity is reached or a memory allocation failure occurs.

◆ pqs_connections_available()

size_t pqs_connections_available ( void )

Get the number of available (inactive) connection states in the collection.

This function iterates through the connection collection and counts the number of entries that are currently marked as inactive.

Returns: Returns the number of available (inactive) connection states.

◆ pqs_connections_clear()

void pqs_connections_clear ( void )

Erase (clear) all the connection collection members.

This function clears the memory for all connection state structures in the collection and resets each active flag to false. It also resets the connection identifier (cid) of each state to its index.

◆ pqs_connections_dispose()

void pqs_connections_dispose ( void )

Dispose of the connection collection state.

This function frees all memory allocated for the connection state array and the corresponding active flag array. It also resets the collection length and maximum capacity to zero.

◆ pqs_connections_full()

bool pqs_connections_full ( void )

Check if the connection collection is full.

The function iterates through the active flags in the connection collection. If every entry is marked as active, the collection is considered full.

Returns: Returns true if all connection state entries are active; otherwise, false.

◆ pqs_connections_get()

pqs_connection_state * pqs_connections_get ( uint32_t instance )

Get a connection state pointer from a given instance number.

The function searches through the connection collection for a connection state whose connection identifier (cid) matches the provided instance number.

Parameters

instance The socket instance number.

Returns: Returns the pointer to the connection state if found; otherwise, returns NULL.

◆ pqs_connections_index()

pqs_connection_state * pqs_connections_index ( size_t index )

Get a connection state pointer by its collection index.

This function returns a pointer to the connection state located at the specified index in the internal connection collection, provided the index is within bounds.

Parameters

index The index number within the connection collection.

Returns: Returns a pointer to the connection state at the given index, or NULL if the index is out of range.

◆ pqs_connections_initialize()

void pqs_connections_initialize	(	size_t	count,
		size_t	maximum )

Initialize the connection collection.

This function allocates and initializes the internal connection collection with the specified number of connection states. A minimum of one connection state is created, and the maximum number of connection states is set to the provided value. Each connection state is initialized by setting its connection identifier (cid) to its index and marking it as inactive.

Parameters

count	The number of initial connection states to allocate (minimum of one).
maximum	The maximum number of connection states allowed (must be greater than or equal to count).

◆ pqs_connections_next()

pqs_connection_state * pqs_connections_next ( void )

Get the next available connection state.

This function searches for the first inactive connection state in the collection and marks it as active. If the collection is already full, it attempts to add a new connection state (subject to the maximum capacity).

Returns: Returns a pointer to the next available (or newly added) connection state, or NULL if none are available.

◆ pqs_connections_reset()

void pqs_connections_reset ( uint32_t instance )

Reset a connection in the collection.

This function finds the connection state with the specified connection identifier (cid) and resets it. The connection state is cleared, its connection identifier is reset to its index, and its active flag is set to false.

Parameters

instance The socket instance number (connection identifier) of the connection to reset.

◆ pqs_connections_self_test()

void pqs_connections_self_test ( void )

Run the self-test for the connection collection.

This function performs a series of tests on the connection collection to verify correct behavior:

Initializes the collection with one connection state and sets the maximum to 10.
Adds nine additional connection states using pqs_connections_next(), resulting in a full collection.
Checks that the number of available connections is zero and that the collection is full.
Resets several connection states (instances 1, 3, 5, 7, and 9) to simulate connection closure.
Verifies that the collection is no longer full.
Reclaims five connection states by calling pqs_connections_next() and confirms that the collection is full again.
Attempts to add an extra connection state beyond the maximum capacity.
Verifies that the collection size remains at the maximum (10).
Finally, clears and disposes of the collection.

This self-test is intended for internal diagnostic purposes to ensure the integrity and proper operation of the connection management functions.

◆ pqs_connections_size()

size_t pqs_connections_size ( void )

Get the total number of connection state items in the collection.

This function returns the current number of connection state items in the internal connection collection.

Returns: Returns the total number of connection state items.

Functions

Detailed Description

Function Documentation

◆ pqs_connections_active()

◆ pqs_connections_add()

◆ pqs_connections_available()

◆ pqs_connections_clear()

◆ pqs_connections_dispose()

◆ pqs_connections_full()

◆ pqs_connections_get()

◆ pqs_connections_index()

◆ pqs_connections_initialize()

◆ pqs_connections_next()

◆ pqs_connections_reset()

◆ pqs_connections_self_test()

◆ pqs_connections_size()