Skip to content

WIP: Document and implement new memory management pattern

Tom Wagner requested to merge ryuukyu/pipewire-rs:new-memory-management into main

Description

Update guidelines for bindings with new design for memory management types and implement them

This adds documentation for a new design for splitting C objects that require memory management into multiple rust types.

Owning types, previously for example "Context" and either Rc-like or Box-like, now exist as both e.g. ContextBox and ContextRc. Non-owning types, previously e.g. ContextRef are now just called Context.

Compared to the old pattern of one owning type (either Rc or Box like) and a ref type, the new approach has some advantages:

  • More flexible owning types due to having both Rc-like and Box-like variants. Use a zero overhead box type if possible, or use an rc type if needed (often to work around lifetimes). Previously, each type only used one of the two.
  • Better naming scheme: The Box suffix makes it clear that the type is a box-like smart pointer, the Rc suffix makes it clear that it is like an Rc, no suffix (previously the Ref suffix) means you're working with the "real" type directly.
  • Works better when using raw C types. We couldn't properly offer from_raw functions to take ownership of a raw pointer, because the Rc-like wrappers also needed to hold structs depended on, e.g. Core held a Context. The Box-like types can do this easily, as they only have a lifetime to those structs, which can stay unbounded.

Overall, I hope to improve the API with this by increasing flexibility and clearness, as well as using this rewrite to consistently implement it throughout the project, as most structs don't even offer a non-owning type yet.

Comments on implementation and especially the design would be appreciated.

Depends on !223 (merged)

Work done

  • Document new design pattern
  • Add Weak Rc types to the design example
  • Implement for MainLoop, Loop
  • Implement for ThreadLoop
  • Implement for Context
  • Implement for Core
  • Implement for Stream
  • Implement for Registry (partly done)
  • Implement for proxies (Node, Port, Link, Client, Device, Factory, Module, Metadata, Proxy)
  • Implement for Properties
  • Implement in libspa crate
  • Adjust and improve documentation
Edited by Tom Wagner

Merge request reports