Map

Files
file	map.h
	pipewire/map.h

Data Structures
struct	pw_map
	A map. More...

Macros
#define	PW_MAP_INIT(extend)
#define	pw_map_get_size(m)
	Get the number of currently allocated elements in the map.
#define	pw_map_get_item(m, id)
#define	pw_map_item_is_free(item)
#define	pw_map_id_is_free(m, id)
#define	pw_map_check_id(m, id)
#define	pw_map_has_item(m, id)
#define	pw_map_lookup_unchecked(m, id)
#define	PW_MAP_ID_TO_PTR(id)
	Convert an id to a pointer that can be inserted into the map.
#define	PW_MAP_PTR_TO_ID(p)
	Convert a pointer to an id that can be retrieved from the map.

Functions
PW_API_MAP void	pw_map_init (struct pw_map *map, size_t size, size_t extend)
	Initialize a map.
PW_API_MAP void	pw_map_clear (struct pw_map *map)
	Clear a map and free the data storage.
PW_API_MAP void	pw_map_reset (struct pw_map *map)
	Reset a map but keep previously allocated storage.
PW_API_MAP uint32_t	pw_map_insert_new (struct pw_map *map, void *data)
	Insert data in the map.
PW_API_MAP int	pw_map_insert_at (struct pw_map *map, uint32_t id, void *data)
	Replace the data in the map at an index.
PW_API_MAP void	pw_map_remove (struct pw_map *map, uint32_t id)
	Remove an item at index.
PW_API_MAP void *	pw_map_lookup (const struct pw_map *map, uint32_t id)
	Find an item in the map.
PW_API_MAP int	pw_map_for_each (const struct pw_map *map, int(*func)(void *item_data, void *data), void *data)
	Iterate all map items.

Detailed Description

A map that holds pointers to objects indexed by id

The map is a sparse version of the pw_array that manages the indices of elements for the caller. Adding items with pw_map_insert_new() returns the assigned index for that item; if items are removed the map re-uses indices to keep the array at the minimum required size.

struct pw_map map = PW_MAP_INIT(4);
 
idx1 = pw_map_insert_new(&map, ptr1);
idx2 = pw_map_insert_new(&map, ptr2);
// the map is now [ptr1, ptr2], size 2
pw_map_remove(&map, idx1);
// the map is now [<unused>, ptr2], size 2
pw_map_insert_new(&map, ptr3);
// the map is now [ptr3, ptr2], size 2

Macro Definition Documentation

PW_MAP_INIT

#define PW_MAP_INIT

(

extend

)

Value:

((struct pw_map) { PW_ARRAY_INIT(extend), SPA_ID_INVALID })

Parameters

extend

the amount of bytes to grow the map with when needed

pw_map_get_size

#define pw_map_get_size

(

m

)

Value:

pw_array_get_len(&(m)->items, union pw_map_item)

Get the number of currently allocated elements in the map.

Note

pw_map_get_size() returns the currently allocated number of elements in the map, not the number of actually set elements.

Returns

the number of available elements before the map needs to grow

pw_map_get_item

#define pw_map_get_item	(		m,
			id )

Value:

pw_array_get_unchecked(&(m)->items,id,union pw_map_item)

pw_map_item_is_free

#define pw_map_item_is_free

(

item

)

Value:

((item)->next & 0x1)

pw_map_id_is_free

#define pw_map_id_is_free	(		m,
			id )

Value:

(pw_map_item_is_free(pw_map_get_item(m,id)))

pw_map_check_id

#define pw_map_check_id	(		m,
			id )

Value:

((id) < pw_map_get_size(m))

Returns

true if the id fits within the current map size

pw_map_has_item

#define pw_map_has_item	(		m,
			id )

Value:

(pw_map_check_id(m,id) && !pw_map_id_is_free(m, id))

Returns

true if there is a valid item at id

pw_map_lookup_unchecked

#define pw_map_lookup_unchecked	(		m,
			id )

Value:

pw_map_get_item(m,id)->data

PW_MAP_ID_TO_PTR

#define PW_MAP_ID_TO_PTR

(

id

)

Value:

(SPA_UINT32_TO_PTR((id)<<1))

Convert an id to a pointer that can be inserted into the map.

PW_MAP_PTR_TO_ID

#define PW_MAP_PTR_TO_ID

(

p

)

Value:

(SPA_PTR_TO_UINT32(p)>>1)

Convert a pointer to an id that can be retrieved from the map.

Function Documentation

pw_map_init()

PW_API_MAP void pw_map_init	(	struct pw_map *	map,
		size_t	size,
		size_t	extend )

Initialize a map.

Parameters

map	the map to initialize
size	the initial size of the map
extend	the amount to bytes to grow the map with when needed

pw_map_clear()

PW_API_MAP void pw_map_clear

(

struct pw_map *

map

)

Clear a map and free the data storage.

All previously returned ids must be treated as invalid.

pw_map_reset()

PW_API_MAP void pw_map_reset

(

struct pw_map *

map

)

Reset a map but keep previously allocated storage.

All previously returned ids must be treated as invalid.

pw_map_insert_new()

PW_API_MAP uint32_t pw_map_insert_new	(	struct pw_map *	map,
		void *	data )

Insert data in the map.

This function causes the map to grow if required.

Parameters

map	the map to insert into
data	the item to add

Returns

the id where the item was inserted or SPA_ID_INVALID when the item can not be inserted.

pw_map_insert_at()

PW_API_MAP int pw_map_insert_at	(	struct pw_map *	map,
		uint32_t	id,
		void *	data )

Replace the data in the map at an index.

Parameters

map	the map to insert into
id	the index to insert at, must be less or equal to pw_map_get_size()
data	the data to insert

Returns

0 on success, -ENOSPC value when the index is invalid or a negative errno

pw_map_remove()

PW_API_MAP void pw_map_remove	(	struct pw_map *	map,
		uint32_t	id )

Remove an item at index.

The id may get re-used in the future.

Parameters

map	the map to remove from
id	the index to remove

pw_map_lookup()

PW_API_MAP void * pw_map_lookup	(	const struct pw_map *	map,
		uint32_t	id )

Find an item in the map.

Parameters

map	the map to use
id	the index to look at

Returns

the item at id or NULL when no such item exists

pw_map_for_each()

PW_API_MAP int pw_map_for_each	(	const struct pw_map *	map,
		int(*	func )(void *item_data, void *data),
		void *	data )

Iterate all map items.

Parameters

map	the map to iterate
func	the function to call for each item, the item data and data is passed to the function. When func returns a non-zero result, iteration ends and the result is returned.
data	data to pass to func

Returns

the result of the last call to func or 0 when all callbacks returned 0.