WIP: Document and implement new memory management pattern
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, theRc
suffix makes it clear that it is like anRc
, no suffix (previously theRef
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 theRc
-like wrappers also needed to hold structs depended on, e.g.Core
held aContext
. TheBox
-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