PipeWire: Map

PipeWire 1.6.5

Loading...
Searching...
No Matches
Map
Utilities

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)
#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
pw_map_remove
PW_API_MAP void pw_map_remove(struct pw_map *map, uint32_t id)
Remove an item at index.
Definition map.h:190
pw_map_insert_new
PW_API_MAP uint32_t pw_map_insert_new(struct pw_map *map, void *data)
Insert data in the map.
Definition map.h:138
PW_MAP_INIT
#define PW_MAP_INIT(extend)
Definition map.h:78
pw_map
A map.
Definition map.h:71

## Macro Definition Documentation

## ◆ PW_MAP_INIT

#define PW_MAP_INIT | ( |  | extend | ) |

Value:
((struct pw_map) { PW_ARRAY_INIT(extend), SPA_ID_INVALID })
PW_ARRAY_INIT
#define PW_ARRAY_INIT(extend)
Initialize an array.
Definition array.h:48
SPA_ID_INVALID
#define SPA_ID_INVALID
Definition defs.h:250

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)
pw_array_get_len
#define pw_array_get_len(a, t)
Get the number of items of type t in array.
Definition array.h:56

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_array_get_unchecked
#define pw_array_get_unchecked(a, idx, t)
Get the item with index idx and type t from array.
Definition array.h:58

## ◆ 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_item_is_free
#define pw_map_item_is_free(item)
Definition map.h:88
pw_map_get_item
#define pw_map_get_item(m, id)
Definition map.h:87

## ◆ pw_map_check_id

#define pw_map_check_id | ( |  | m,
|  |  | id )

Value:
((id) < pw_map_get_size(m))
id
uint32_t id
Definition core.h:432
pw_map_get_size
#define pw_map_get_size(m)
Get the number of currently allocated elements in the map.
Definition map.h:86

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))
pw_map_check_id
#define pw_map_check_id(m, id)
Definition map.h:91
pw_map_id_is_free
#define pw_map_id_is_free(m, id)
Definition map.h:89

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))
SPA_UINT32_TO_PTR
#define SPA_UINT32_TO_PTR(u)
Definition defs.h:243

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)
SPA_PTR_TO_UINT32
#define SPA_PTR_TO_UINT32(p)
Definition defs.h:241

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.