list.h File Reference

Memory-aligned list management functions. More...

#include "common.h"

Go to the source code of this file.

Data Structures
struct	qsc_list_state
	Contains the list context state. More...

Macros
#define	QSC_LIST_ALIGNMENT   64ULL
	The internal memory alignment constant.
#define	QSC_LIST_MAX_DEPTH   102400ULL
	The maximum list depth.

Functions
QSC_EXPORT_API void	qsc_list_add (qsc_list_state *ctx, void *item)
	Add an item to the list.
QSC_EXPORT_API void	qsc_list_copy (const qsc_list_state *ctx, size_t index, void *item)
	Copy an item from the list.
QSC_EXPORT_API size_t	qsc_list_count (const qsc_list_state *ctx)
	Get the number of items in the list.
QSC_EXPORT_API void	qsc_list_deserialize (qsc_list_state *ctx, const uint8_t *input)
	Convert a serialized list into a list context.
QSC_EXPORT_API void	qsc_list_dispose (qsc_list_state *ctx)
	Dispose of the list state.
QSC_EXPORT_API void	qsc_list_initialize (qsc_list_state *ctx, size_t width)
	Initialize the list state.
QSC_EXPORT_API bool	qsc_list_empty (const qsc_list_state *ctx)
	Check if the list is empty.
QSC_EXPORT_API bool	qsc_list_full (const qsc_list_state *ctx)
	Check if the list is full.
QSC_EXPORT_API void	qsc_list_item (const qsc_list_state *ctx, uint8_t *item, size_t index)
	Retrieve a pointer to a list item.
QSC_EXPORT_API void	qsc_list_rshuffle (qsc_list_state *ctx)
	Randomly shuffle the items in the list.
QSC_EXPORT_API void	qsc_list_remove (qsc_list_state *ctx, size_t index)
	Remove an item from the list.
QSC_EXPORT_API size_t	qsc_list_serialize (uint8_t *output, const qsc_list_state *ctx)
	Serialize the list into a byte array.
QSC_EXPORT_API size_t	qsc_list_size (const qsc_list_state *ctx)
	Get the serialized size of the list.
QSC_EXPORT_API void	qsc_list_sort (qsc_list_state *ctx)
	Sort the items in the list.

Detailed Description

Memory-aligned list management functions.

This header defines the public API for managing a memory-aligned list data structure. The list is designed to store items in a contiguous memory block with a specified width (in bytes), ensuring proper alignment for performance-critical operations and compatibility with SIMD instructions.

The module provides functions to:

• Initialize and allocate a memory-aligned list.
• Add and remove items from the list.
• Copy list contents.
• Sort the list using efficient algorithms.
• Serialize and deserialize the list to/from binary formats.
• Perform self-tests to verify the integrity and functionality of the list.

This design is ideal for cryptographic and high-performance applications where data alignment is crucial for optimal hardware utilization.

// Example usage:
// Initialize a list capable of holding 100 items, each 64 bytes wide.
qsc_list_state myList;
qsc_list_initialize(&myList, 100, 64);
 
// Add an item to the list.
uint8_t item[64] = { ... item data ... };
qsc_list_add(&myList, item);
 
// Sort the list.
qsc_list_sort(&myList);
 
// Serialize the list into a binary format.
uint8_t* serialized = list_serialize(&myList);
 
// Clean up and free allocated resources.
qsc_list_dispose(&myList);

Reference Links:

Intel 64 and IA-32 Architectures Software Developer's Manual GCC Data Alignment Documentation

Function Documentation

qsc_list_add()

QSC_EXPORT_API void qsc_list_add	(	qsc_list_state *	ctx,
		void *	item )

Add an item to the list.

Parameters

ctx	[qsc_list_state*] Pointer to the list state structure.
item	[void*] Pointer to the item to be added.

qsc_list_copy()

QSC_EXPORT_API void qsc_list_copy	(	const qsc_list_state *	ctx,
		size_t	index,
		void *	item )

Copy an item from the list.

Parameters

ctx	[const qsc_list_state*] Pointer to the list state structure.
index	[size_t] The index number of the list item.
item	[void*] Pointer to the memory that receives the copy.

qsc_list_count()

QSC_EXPORT_API size_t qsc_list_count

(

const qsc_list_state *

ctx

)

Get the number of items in the list.

Parameters

ctx	[const qsc_list_state*] Pointer to the list state structure.

Returns

[size_t] Returns the number of items in the list.

qsc_list_deserialize()

QSC_EXPORT_API void qsc_list_deserialize	(	qsc_list_state *	ctx,
		const uint8_t *	input )

Convert a serialized list into a list context.

Parameters

ctx	[qsc_list_state*] Pointer to the list state structure.
input	[const uint8_t*] Pointer to the serialized list.

qsc_list_dispose()

QSC_EXPORT_API void qsc_list_dispose

(

qsc_list_state *

ctx

)

Dispose of the list state.

Parameters

ctx	[qsc_list_state*] Pointer to the list state structure.

qsc_list_empty()

QSC_EXPORT_API bool qsc_list_empty

(

const qsc_list_state *

ctx

)

Check if the list is empty.

Parameters

ctx	[const qsc_list_state*] Pointer to the list state structure.

Returns

[bool] Returns true if the list is empty.

qsc_list_full()

QSC_EXPORT_API bool qsc_list_full

(

const qsc_list_state *

ctx

)

Check if the list is full.

Parameters

ctx	[const qsc_list_state*] Pointer to the list state structure.

Returns

[bool] Returns true if the list is full.

qsc_list_initialize()

QSC_EXPORT_API void qsc_list_initialize	(	qsc_list_state *	ctx,
		size_t	width )

Initialize the list state.

Parameters

ctx	[qsc_list_state*] Pointer to the list state structure.
width	[size_t] The maximum size of each list item in bytes.

qsc_list_item()

QSC_EXPORT_API void qsc_list_item	(	const qsc_list_state *	ctx,
		uint8_t *	item,
		size_t	index )

Retrieve a pointer to a list item.

Parameters

ctx	[const qsc_list_state*] Pointer to the list state structure.
item	[uint8_t*] Pointer to the buffer that receives the item.
index	[size_t] The index of the list item.

qsc_list_remove()

QSC_EXPORT_API void qsc_list_remove	(	qsc_list_state *	ctx,
		size_t	index )

Remove an item from the list.

Parameters

ctx	[qsc_list_state*] Pointer to the list state structure.
index	[size_t] The index number of the item to remove.

qsc_list_rshuffle()

QSC_EXPORT_API void qsc_list_rshuffle

(

qsc_list_state *

ctx

)

Randomly shuffle the items in the list.

Parameters

ctx	[qsc_list_state*] Pointer to the list state structure.

qsc_list_serialize()

QSC_EXPORT_API size_t qsc_list_serialize	(	uint8_t *	output,
		const qsc_list_state *	ctx )

Serialize the list into a byte array.

Parameters

output	[uint8_t*] Pointer to the output serialized array.
ctx	[const qsc_list_state*] Pointer to the list state structure.

Returns

[size_t] Returns the number of bytes in the serialized list.

qsc_list_size()

QSC_EXPORT_API size_t qsc_list_size

(

const qsc_list_state *

ctx

)

Get the serialized size of the list.

Parameters

ctx	[const qsc_list_state*] Pointer to the list state structure.

Returns

[size_t] Returns the byte size of the serialized list.

qsc_list_sort()

QSC_EXPORT_API void qsc_list_sort

(

qsc_list_state *

ctx

)

Sort the items in the list.

Parameters

ctx	[qsc_list_state*] Pointer to the list state structure.