Hello @kbar,
thank you for reaching out to us and thank you for pointing this out. Your own findings are mostly correct, and the argument transferOwnership
is indeed explained incorrectly, or at least very ambiguously, depending on how one does interpret "the caller". SetMemoryReadMode
does among other things the following:
void Filename::SetMemoryReadMode(void *adr, Int size, Bool transferOwnership)
{
// ... other stuff
MemoryFileStruct mfs;
if (!mfs)
return;
mfs->t_mem = adr;
mfs->t_size = size;
mfs->t_mode = MFSMODE::READ;
if (transferOwnership)
mfs->t_mode |= MFSMODE::FREEMEM;
mfs->t_mode = MFSMODE::WRITE | MFSMODE::FREEMEM;
maxon::Url memname(SOMETHING_INTERNAL);
// .. other stuff
// _url is a maxon::Url field attached to Filename
_url = memname;
And then there is an internal implementation for MemoryFileStruct
called MemoryFileStructI
which has the destructor:
MemoryFileStructI::~MemoryFileStructI(void)
{
if (t_mode & MFSMODE::FREEMEM)
DeleteMem(t_mem);
t_size = 0;
t_mode = MFSMODE::NONE;
}
So, when you do pass true
for transferOwnership
to SetMemoryReadMode
, the associated memory is being freed on the deallocation of the internally used MemoryFileStruct
. And if not, you would have to call DeleteMem(adr) yourself, where adr
is the void pointer, you did pass into SetMemoryReadMode
.
This is further complicated by the fact that MemoryFileStruct
is a maxon::StrongRef
to maxon::FileStructI
,
class MemoryFileStruct : public maxon::StrongRef<MemoryFileStructI>
{
...
i.e., reference counted itself, so the mfs
variable at the top will be deallocated automatically once the scope of SetMemoryReadMode
is being left. On top of that, Filename
internally now wraps around maxon::Url
, its somewhat maxon API replacement, as shown in the first snippet.
So, long story short, I would always pass true
for transferOwnership
, unless you want to cast the address adr
into something more useful yourself after the method has been left. This is all caused by the sometimes a bit awkward bridges that are being built internally between the classic API and the maxon API, in this case that the Filename
is really an maxon::Url
internally.
We will fix the documentation for transferOwnership
for an upcoming release, although it will definitely not the upcoming one, as it is already too late for that.
I hope this helps and cheers,
Ferdinand