Reference Counting under the Hood (C API)

[endeav0r]

It looks like objects have some reference-counting mechanism under the hood. It would be nice if there was some more documentation on this.

For example, let's say I have an HLIL Function, and I want to start enumerating blocks and instructions. I call BNGetHighLevelILBasicBlockList to get my block list, and then walk through that to get objects of type BNBasicBlock. From the BNBasicBlock I can get start/end indices, which allow me to fetch instructions from the original BNHighLevelILFunction with BNGetHighLevelILByIndex.

If I don't want to save references to all of these things, I can retrieve the BNHighLevelILFunction from the BNBasicBlock. I can call:

BNHighLevelILFunction* f = BNGetFunctionHighLevelIL(BNGetBasicBlockFunction(block));

If I do this, am I leaking memory? Should I assume that whenever I get a pointer back from the API, that thing has a reference of 1, and I should always call free on it? Should I instead be doing:

BNFunction* function = BNGetBasicBlockFunction(block);
BNHighLevelILFunction * hlil_function = BNGetFunctionHighLevelIL(function);
BNFreeFunction(function)

What are the rules for references on things returned from the C API. What should I track, and what should I assume Binary Ninja will track, and when?

[rssor]

Generally speaking when we return an object the refcount will already have been increased, meaning you are responsible for freeing it. There are certain exceptions, for example in situations where we return arrays every element in the array has its refcount increased but will be all be decremented when the free function over the entire list gets called.

The other major exception is when receiving object pointers in callbacks, where since the core already holds a refcount you don't need to add/remove references.

The best approach will be to look at what the C++/Python bindings do.