PipeWire: Map

PipeWire 0.3.66

Loading...
Searching...
No Matches
Files | Data Structures | Macros | Functions
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) ((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.
#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.
#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.

## Functions
static void | pw_map_init (struct pw_map *map, size_t size, size_t extend)
| Initialize a map.
static void | pw_map_clear (struct pw_map *map)
| Clear a map and free the data storage.
static void | pw_map_reset (struct pw_map *map)
| Reset a map but keep previously allocated storage.
static uint32_t | pw_map_insert_new (struct pw_map *map, void *data)
| Insert data in the map.
static int | pw_map_insert_at (struct pw_map *map, uint32_t id, void *data)
| Replace the data in the map at an index.
static void | pw_map_remove (struct pw_map *map, uint32_t id)
| Remove an item at index.
static void * | pw_map_lookup (struct pw_map *map, uint32_t id)
| Find an item in the map.
static int | pw_map_for_each (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
static void pw_map_remove(struct pw_map *map, uint32_t id)
Remove an item at index.
Definition: map.h:205
pw_map_insert_new
static uint32_t pw_map_insert_new(struct pw_map *map, void *data)
Insert data in the map.
Definition: map.h:153
PW_MAP_INIT
#define PW_MAP_INIT(extend)
Definition: map.h:93
pw_map
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

  extend | the 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

  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()

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

  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()

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

  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()

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

  map | the map to remove from
  id | the 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

  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()

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

  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.