PipeWire  0.3.45

A map that holds pointers to objects indexed by id. More...

Files

file  map.h
 pipewire/map.h
 

Data Structures

struct  pw_map
 A map. More...
 

Macros

#define PW_MAP_INIT(extend)   (struct pw_map) { PW_ARRAY_INIT(extend), SPA_ID_INVALID }
 
#define pw_map_get_size(m)   pw_array_get_len(&(m)->items, union pw_map_item)
 Get the number of currently allocated elements in the map. More...
 
#define pw_map_get_item(m, id)   pw_array_get_unchecked(&(m)->items,id,union pw_map_item)
 
#define pw_map_item_is_free(item)   ((item)->next & 0x1)
 
#define pw_map_id_is_free(m, id)   (pw_map_item_is_free(pw_map_get_item(m,id)))
 
#define pw_map_check_id(m, id)   ((id) < pw_map_get_size(m))
 
#define pw_map_has_item(m, id)   (pw_map_check_id(m,id) && !pw_map_id_is_free(m, id))
 
#define pw_map_lookup_unchecked(m, id)   pw_map_get_item(m,id)->data
 
#define PW_MAP_ID_TO_PTR(id)   (SPA_UINT32_TO_PTR((id)<<1))
 Convert an id to a pointer that can be inserted into the map. More...
 
#define PW_MAP_PTR_TO_ID(p)   (SPA_PTR_TO_UINT32(p)>>1)
 Convert a pointer to an id that can be retrieved from the map. More...
 

Functions

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

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
static void pw_map_remove(struct pw_map *map, uint32_t id)
Remove an item at index.
Definition: map.h:205
static uint32_t pw_map_insert_new(struct pw_map *map, void *data)
Insert data in the map.
Definition: map.h:153
#define PW_MAP_INIT(extend)
Definition: map.h:93
A map.
Definition: map.h:86

Macro Definition Documentation

◆ PW_MAP_INIT

#define PW_MAP_INIT (   extend)    (struct pw_map) { PW_ARRAY_INIT(extend), SPA_ID_INVALID }
Parameters
extendthe amount of bytes to grow the map with when needed

◆ pw_map_get_size

#define pw_map_get_size (   m)    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 
)    pw_array_get_unchecked(&(m)->items,id,union pw_map_item)

◆ pw_map_item_is_free

#define pw_map_item_is_free (   item)    ((item)->next & 0x1)

◆ pw_map_id_is_free

#define pw_map_id_is_free (   m,
  id 
)    (pw_map_item_is_free(pw_map_get_item(m,id)))

◆ pw_map_check_id

#define pw_map_check_id (   m,
  id 
)    ((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 
)    (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 
)    pw_map_get_item(m,id)->data

◆ PW_MAP_ID_TO_PTR

#define PW_MAP_ID_TO_PTR (   id)    (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)    (SPA_PTR_TO_UINT32(p)>>1)

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

Function Documentation

◆ pw_map_init()

static void pw_map_init ( struct pw_map map,
size_t  size,
size_t  extend 
)
inlinestatic

Initialize a map.

Parameters
mapthe map to initialize
sizethe initial size of the map
extendthe amount to bytes to grow the map with when needed

◆ pw_map_clear()

static void pw_map_clear ( struct pw_map map)
inlinestatic

Clear a map and free the data storage.

All previously returned ids must be treated as invalid.

◆ pw_map_reset()

static void pw_map_reset ( struct pw_map map)
inlinestatic

Reset a map but keep previously allocated storage.

All previously returned ids must be treated as invalid.

◆ pw_map_insert_new()

static uint32_t pw_map_insert_new ( struct pw_map map,
void *  data 
)
inlinestatic

Insert data in the map.

This function causes the map to grow if required.

Parameters
mapthe map to insert into
datathe 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()

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

Replace the data in the map at an index.

Parameters
mapthe map to insert into
idthe index to insert at, must be less or equal to pw_map_get_size()
datathe data to insert
Returns
0 on success, -ENOSPC value when the index is invalid or a negative errno

◆ pw_map_remove()

static void pw_map_remove ( struct pw_map map,
uint32_t  id 
)
inlinestatic

Remove an item at index.

The id may get re-used in the future.

Parameters
mapthe map to remove from
idthe index to remove

◆ pw_map_lookup()

static void* pw_map_lookup ( struct pw_map map,
uint32_t  id 
)
inlinestatic

Find an item in the map.

Parameters
mapthe map to use
idthe index to look at
Returns
the item at id or NULL when no such item exists

◆ pw_map_for_each()

static int pw_map_for_each ( struct pw_map map,
int(*)(void *item_data, void *data)  func,
void *  data 
)
inlinestatic

Iterate all map items.

Parameters
mapthe map to iterate
functhe 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.
datadata to pass to func
Returns
the result of the last call to func or 0 when all callbacks returned 0.