Ownership model

Explain how xkbcommon handle object’s ownership.

Types of ownership

xkbcommon uses 3 types of ownership:

Types of ownership

Ownership	Allocator	Allocation	References	Examples
Exclusive	User	Stack / caller managed	None	xkb_keymap_key_iterator, xkb_keymap_serialize_config
	xkbcommon	Heap	Exclusive (sole owner)	xkb_events
Shared			Ref-counted	xkb_context, xkb_keymap

Object transfer

@important xkbcommon never takes ownership of caller-allocated memory. In particular, caller-provided buffers and strings are either borrowed for the duration of a function call or internally copied.

Remarks

Unlike languages such as Rust, C does not enforce immutability or borrowing rules. Users are expected to respect the intended immutability and lifetime guarantees documented by xkbcommon.

xkbcommon objects follow the following transfer rules:

Modes of object transfer

Mode	Description	Example text
Call-borrowed	The object is borrowed for the duration of the function call and is not retained after the function returns. The corresponding argument is const-qualified for an immutable borrow; exceptions are documented for legacy API. Note It is the default transfer mode for function arguments.	enum Baz foo_get_something(const struct Foo *foo); enum xkb_status foo_do_something(struct Foo *foo); *(no documentation text for the default argument transfer mode)*
Frame-borrowed	The object is borrowed for the lifetime of the corresponding frame and must not be retained. It is stricter than the lifetime of the frame container, as a frame can be overriden or reallocated by the container. The corresponding argument is const-qualified for an immutable borrow; exceptions are documented for legacy API.	const struct Bar* bar = foo_next(struct Foo *foo); ‍bar is only valid during the corresponding frame stored in foo.
Retained-borrowed	The recipient retains a borrowed pointer to the object without acquiring ownership. The object must remain valid for the entire lifetime of the recipient. The corresponding argument or return is const-qualified to denote an immutable borrow; exceptions are documented for legacy API.	struct Foo* foo_new(const struct Bar *bar); ‍Newly allocated Foo object borrows *bar. enum xkb_status foo_init(struct Foo *foo, const struct Bar *bar); ‍*foo borrows *bar.
Owned	Ownership of the object is transferred to the recipient. For a reference-counted type, this means the recipient owns one reference on the value. Such function arguments or return values are never const-qualified, because they need to modify the reference counter. Remarks Reminder: xkbcommon never takes ownership of caller-allocated memory. For a reference-counted parameter, the recipient’s reference keeps the parameter valid for the recipient’s entire lifetime; you may release your own reference once the call returns. Note Owned is the default mode for function return values.	struct Foo* foo_new(enum foo_flags flags); *(no documentation text for the default return value transfer mode)* struct Foo* foo_new(struct Bar *bar); ‍Newly allocated Foo object shares ownership of *bar via a new reference. enum xkb_status foo_set_bar(struct Foo *foo, struct Bar *bar); ‍foo shares ownership of *bar via a new reference.