HaikuBook: terminology for ownership and ownership transfer of objects

[nielx]

As a general improvement to the HaikuBook (and to some extend the Haiku API), we may try to make users more aware of the ownership and lifetime of objects. It would be good to make sure the BeBook has some consistent terminology that helps the user use the API properly, without running into issues like memory leaks and segmentation faults.

Excerpt from an exchange from ​Gerrit

Nielx: The borrowed reference is indeed a rust-ism and it is semi-intentional. The background is that working with Rust gives me the proper ways of thinking about ownership, which has always been part of C++ and Haiku, but having it been made explicit, also gave me the tools to apply it to other situations. So yes, the concept of ownership (and lifetimes) will be more explicit in documentation that I will write.

Having said that, I know 'borrowed reference' is a poor transplant, especially since C++ itself introduces a first class concept of references (which in a sense act exactly like 'borrowed' references). In an earlier draft I used the term 'borrowed pointer', but it feels misleading, as it is not the pointer itself that is borrowed, but the underlying object.

Pulkomandy: Well, the C++ indeed leaves this all implicit, but the Be API has explicit things in some places. For example, BBitmap has SetBits (makes a copy of the data) and AdoptBit (takes ownership of the original data). And I guess the opposite would be having Get...() and Create...() methods to indicate the ownership of the returned pointer.

Having spent too much time in C++, the concept is quite natural to me, and I would infer it from documentation that says things like:

Returns a pointer to the foo (that returns only a pointer, which implies the object itself keeps its existing ownership)

Returns a newly allocated foo (returns the object itself, through a pointer, which implies the caller takes ownership)

But, that may be too subtle for people not used to it.

The Be Book mentions it in some places as "the caller must free the object" or "the function takes ownership of the object, it must not be freed". Which I think is a bit too low level. In any case, maybe the concept of object ownership should be documented somewhere separately ("special topics" in Be Book way) and then we can introduce and define whatever vocabulary we decide to use. Then, it's fine to import concepts from Rust, without assuming readers already know about them.