mcutil.h File Reference

#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
#include <limits.h>
#include <string.h>
#include <unistd.h>
#include <pthread.h>
#include <stdbool.h>
#include "mcbsp.h"
#include "mcbsp-affinity.h"

Include dependency graph for mcutil.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	mcbsp_util_machine_info
	Structure representing the machine hardware information. More...
struct	mcbsp_util_address_map
	A map from pointers to unsigned long ints. More...
struct	mcbsp_util_address_table_entry
	A single address table entry. More...
struct	mcbsp_util_stack
	Self-growing stack. More...
struct	mcbsp_util_address_table
	A table of local address locations per SPMD variable. More...

Functions
void	mcbsp_util_stack_initialise (struct mcbsp_util_stack *const stack, const size_t elementSize)
	Initialises the mcbsp_util_stack struct.
void	mcbsp_util_stack_grow (struct mcbsp_util_stack *const stack)
	Doubles the capacity of a given stack.
bool	mcbsp_util_stack_empty (const struct mcbsp_util_stack *const stack)
	Checks whether a given stack is empty.
void *	mcbsp_util_stack_pop (struct mcbsp_util_stack *const stack)
	Returns the newest item in the stack.
void *	mcbsp_util_stack_peek (const struct mcbsp_util_stack *const stack)
	Returns the top stack item.
void	mcbsp_util_stack_push (struct mcbsp_util_stack *const stack, const void *const item)
	Pushes a new item on the stack.
void	mcbsp_util_stack_destroy (struct mcbsp_util_stack *const stack)
	Frees all memory related to a given stack.
void	mcbsp_util_varstack_grow (struct mcbsp_util_stack *const stack)
	Doubles the capacity of a given stack.
void *	mcbsp_util_varstack_pop (struct mcbsp_util_stack *const stack, const size_t size)
	Returns the top variable stack item.
void *	mcbsp_util_varstack_regpop (struct mcbsp_util_stack *const stack)
	Returns the top fixed-size item of the stack.
void *	mcbsp_util_varstack_peek (const struct mcbsp_util_stack *const stack, const size_t size)
	Peeks for a variably-sized item on the stack.
void	mcbsp_util_varstack_push (struct mcbsp_util_stack *const stack, const void *const item, const size_t size)
	Pushes a variably-sized item on the stack.
void	mcbsp_util_varstack_regpush (struct mcbsp_util_stack *const stack, const void *const item)
	Pushes a fixed-size item on the stack.
void	mcbsp_util_address_table_initialise (struct mcbsp_util_address_table *const table, const unsigned long int P)
	Initialises the mcbsp_util_address_table struct.
void	mcbsp_util_address_table_grow (struct mcbsp_util_address_table *const table)
	Doubles the capacity of a given address table.
void	mcbsp_util_address_setsize (struct mcbsp_util_address_table *const table, const unsigned long int target_size)
	Ensures the address table is of at least the given size.
void	mcbsp_util_address_table_destroy (struct mcbsp_util_address_table *const table)
	Frees the memory associated with a given address table.
void	mcbsp_util_address_table_set (struct mcbsp_util_address_table *const table, const unsigned long int key, const unsigned long int version, void *const value, const size_t size)
	Sets an entry in a given address table.
struct mcbsp_util_address_table_entry *	mcbsp_util_address_table_get (const struct mcbsp_util_address_table *const table, const unsigned long int key, const unsigned long int version)
	Gets an entry from a given address table.
bool	mcbsp_util_address_table_delete (struct mcbsp_util_address_table *const table, const unsigned long int key, const unsigned long int version)
	Removes an entry from a given address table.
void	mcbsp_util_address_map_initialise (struct mcbsp_util_address_map *const address_map)
	Initialises a mcbsp_util_address_map struct.
void	mcbsp_util_address_map_grow (struct mcbsp_util_address_map *const address_map)
	Doubles the capacity of a given address map.
void	mcbsp_util_address_map_destroy (struct mcbsp_util_address_map *const address_map)
	Frees the memory related to a given address map.
unsigned long int	mcbsp_util_address_map_get (const struct mcbsp_util_address_map *const address_map, const void *const key)
	Address map accessor.
void	mcbsp_util_address_map_insert (struct mcbsp_util_address_map *const address_map, void *const key, unsigned long int value)
	Inserts a key-value pair in the map.
void	mcbsp_util_address_map_remove (struct mcbsp_util_address_map *const address_map, void *const key)
	Removes a key-value pair from the map.
size_t	mcbsp_util_address_map_binsearch (const struct mcbsp_util_address_map *const address_map, const void *const key, size_t lo, size_t hi)
	Helper-function for mcbsp_util_address_map_insert, and mcbsp_util_address_map_remove.
size_t	mcbsp_util_detect_hardware_threads ()
	Attempts to detect the number of hard-ware threads supported on the current machine.
struct mcbsp_util_machine_info *	mcbsp_util_createMachineInfo ()
	Creates a new machine info struct.
void	mcbsp_util_destroyMachineInfo (void *machine_info)
	If a current machine info instance exists, destroys it.
int	mcbsp_util_int_compare (const void *a, const void *b)
	Comparison function for use with qsort on arrays of size_t's.
size_t	mcbsp_util_log2 (size_t x)
	Binary logarithm, unsigned integer version, rounding up.
size_t	mcbsp_util_sort_unique_integers (size_t *const array, const size_t length, const size_t lower_bound, const size_t upper_bound)
	Sorts an array of integers.
bool	mcbsp_util_contains (const size_t *const array, const size_t value, const size_t lo, const size_t hi)
	Returns whether an array contains a given value.
int *	mcbsp_util_pinning (const MCBSP_PROCESSOR_INDEX_DATATYPE P, struct mcbsp_util_machine_info *const machine)
	Function that yields a pinning of P threads according to the given machine info.
void	mcbsp_util_fatal ()
	Handles a fatal error in a uniform fashion.

---

Function Documentation

size_t mcbsp_util_address_map_binsearch	(	const struct mcbsp_util_address_map *const	address_map,
		const void *const	key,
		size_t	lo,
		size_t	hi
	)

Helper-function for mcbsp_util_address_map_insert, and mcbsp_util_address_map_remove.

Performs a binary search for key and returns the largest index for which the map key is less or equal to the supplied key value.

Parameters:

address_map	Pointer to the map to look in.
key	The key value to look for.
lo	Lower bound on range of the map to look for.
hi	upper bound (inclusive) on range of the map to look for.

void mcbsp_util_address_map_destroy

(

struct mcbsp_util_address_map *const

address_map

)

Frees the memory related to a given address map.

Parameters:

address_map

Pointer to the struct to destroy.

unsigned long int mcbsp_util_address_map_get	(	const struct mcbsp_util_address_map *const	address_map,
		const void *const	key
	)

Address map accessor.

Parameters:

address_map	Pointer to the map to consult.
key	Which key to search for.

Returns:

The value associated with the key.

void mcbsp_util_address_map_grow

(

struct mcbsp_util_address_map *const

address_map

)

Doubles the capacity of a given address map.

Parameters:

address_map

Pointer to the struct of the map to increase storage of.

void mcbsp_util_address_map_initialise

(

struct mcbsp_util_address_map *const

address_map

)

Initialises a mcbsp_util_address_map struct.

Parameters:

address_map

Pointer to the struct to initialise.

void mcbsp_util_address_map_insert	(	struct mcbsp_util_address_map *const	address_map,
		void *const	key,
		unsigned long int	value
	)

Inserts a key-value pair in the map.

Parameters:

address_map	Pointer to the map to insert in.
key	Under which key to insert the value.
value	The value to insert.

void mcbsp_util_address_map_remove	(	struct mcbsp_util_address_map *const	address_map,
		void *const	key
	)

Removes a key-value pair from the map.

Does nothing when the key is not in the map.

Parameters:

address_map	Pointer to the map to remove from.
key	Key of the key-value pair to remove.

void mcbsp_util_address_setsize	(	struct mcbsp_util_address_table *const	table,
		const unsigned long int	target_size
	)

Ensures the address table is of at least the given size.

This function is thread-safe.

Parameters:

table	Pointer to the struct to initialise.
target_size	The (new) minimum size of the table after function exit.

bool mcbsp_util_address_table_delete	(	struct mcbsp_util_address_table *const	table,
		const unsigned long int	key,
		const unsigned long int	version
	)

Removes an entry from a given address table.

Does not do boundary checks.

Parameters:

table	Pointer to the address table.
key	Which entry to remove.
version	Which local version to remove.

Returns:

Whether the registration stack at (key,version) is empty.

void mcbsp_util_address_table_destroy

(

struct mcbsp_util_address_table *const

table

)

Frees the memory associated with a given address table.

Parameters:

table

Pointer to the struct to destroy.

struct mcbsp_util_address_table_entry* mcbsp_util_address_table_get ( const struct mcbsp_util_address_table *const  table, const unsigned long int  key, const unsigned long int  version  )

read

Gets an entry from a given address table.

Does not do boundary checks.

Parameters:

table	Pointer to the address table.
key	Which entry to get.
version	Which local version to obtain.

Returns:

The requested address pointer.

void mcbsp_util_address_table_grow

(

struct mcbsp_util_address_table *const

table

)

Doubles the capacity of a given address table.

This function is not thread-safe.

Parameters:

table

Pointer to the struct of the table to increase storage of.

void mcbsp_util_address_table_initialise	(	struct mcbsp_util_address_table *const	table,
		const unsigned long int	P
	)

Initialises the mcbsp_util_address_table struct.

This function is not thread-safe.

Parameters:

table	Pointer to the struct to initialise.
P	The number of local versions to maintain for each entry.

void mcbsp_util_address_table_set	(	struct mcbsp_util_address_table *const	table,
		const unsigned long int	key,
		const unsigned long int	version,
		void *const	value,
		const size_t	size
	)

Sets an entry in a given address table.

Grows table capacity if required.

Parameters:

table	Pointer to the address table.
key	Which entry to set.
version	Which local version to set.
value	Pointer to the local memory region..
size	Size of the local memory region.

bool mcbsp_util_contains	(	const size_t *const	array,
		const size_t	value,
		const size_t	lo,
		const size_t	hi
	)

Returns whether an array contains a given value.

Only the range [lo,hi) of array is checked for value.

Parameters:

array	Where to search in.
value	The value to search for.
lo	From which index on to search (inclusive).
hi	Up to which index to search (exclusive).

Returns:

Whether array contains value in the given range.

struct mcbsp_util_machine_info* mcbsp_util_createMachineInfo ( )

read

Creates a new machine info struct.

Returns:

A pointer to a new machine info struct.

void mcbsp_util_destroyMachineInfo

(

void *

machine_info

)

If a current machine info instance exists, destroys it.

This function is not thread-safe.

Parameters:

machine_info

Pointer to the machine info to deallocate properly.

size_t mcbsp_util_detect_hardware_threads

(

)

Attempts to detect the number of hard-ware threads supported on the current machine.

Returns:

Detected number of HW threads.

void mcbsp_util_fatal

(

)

Handles a fatal error in a uniform fashion.

Only call this function if the error is fatal and unrecoverable, and should thus stop the entire parallel execution.

int mcbsp_util_int_compare	(	const void *	a,
		const void *	b
	)

Comparison function for use with qsort on arrays of size_t's.

size_t mcbsp_util_log2

(

size_t

x

)

Binary logarithm, unsigned integer version, rounding up.

Note: returns 0 for x=0.

int* mcbsp_util_pinning	(	const MCBSP_PROCESSOR_INDEX_DATATYPE	P,
		struct mcbsp_util_machine_info *const	machine
	)

Function that yields a pinning of P threads according to the given machine info.

Parameters:

P	The number of threads to pin.
machine	The machine to pin for.

Returns:

An array R where R[i] gives the core to which thread i should pin to.

size_t mcbsp_util_sort_unique_integers	(	size_t *const	array,
		const size_t	length,
		const size_t	lower_bound,
		const size_t	upper_bound
	)

Sorts an array of integers.

The array is assumed to hold unique elements in a given range of values. The algorithm runs linearly in the amount of possible values.

Parameters:

array	The array to sort.
length	Length of array.
lower_bound	Lower bound (inclusive) on values in array.
upper_bound	Upper bound (exclusive) on values in array.

Returns:

Size of the sorted array.

void mcbsp_util_stack_destroy

(

struct mcbsp_util_stack *const

stack

)

Frees all memory related to a given stack.

bool mcbsp_util_stack_empty

(

const struct mcbsp_util_stack *const

stack

)

Checks whether a given stack is empty.

void mcbsp_util_stack_grow

(

struct mcbsp_util_stack *const

stack

)

Doubles the capacity of a given stack.

void mcbsp_util_stack_initialise	(	struct mcbsp_util_stack *const	stack,
		const size_t	elementSize
	)

Initialises the mcbsp_util_stack struct.

Parameters:

stack	The stack to initialise.
elementSize	The size of a single element in the stack.

void* mcbsp_util_stack_peek

(

const struct mcbsp_util_stack *const

stack

)

Returns the top stack item.

Does not remove it from the stack.

Does not do boundary checking! Call mcbsp_util_stack_empty first when unsure if the stack still contains items.

Returns:

A pointer to the top element in the stack.

void* mcbsp_util_stack_pop

(

struct mcbsp_util_stack *const

stack

)

Returns the newest item in the stack.

This function removes that item from the stack.

Does not do boundary checking! Call mcbsp_util_stack_empty first when unsure if the stack still contains items.

Returns:

A pointer to the next element in the stack.

void mcbsp_util_stack_push	(	struct mcbsp_util_stack *const	stack,
		const void *const	item
	)

Pushes a new item on the stack.

void mcbsp_util_varstack_grow

(

struct mcbsp_util_stack *const

stack

)

Doubles the capacity of a given stack.

void* mcbsp_util_varstack_peek	(	const struct mcbsp_util_stack *const	stack,
		const size_t	size
	)

Peeks for a variably-sized item on the stack.

void* mcbsp_util_varstack_pop	(	struct mcbsp_util_stack *const	stack,
		const size_t	size
	)

Returns the top variable stack item.

void mcbsp_util_varstack_push	(	struct mcbsp_util_stack *const	stack,
		const void *const	item,
		const size_t	size
	)

Pushes a variably-sized item on the stack.

void* mcbsp_util_varstack_regpop

(

struct mcbsp_util_stack *const

stack

)

Returns the top fixed-size item of the stack.

void mcbsp_util_varstack_regpush	(	struct mcbsp_util_stack *const	stack,
		const void *const	item
	)

Pushes a fixed-size item on the stack.