Filename::SetMemoryReadMode Docs don't seem right.
-
The documentation shown below for Filename::SetMemoryReadMode does not look right at all.
This method is used to pass data to the Filename. So if transferownership is set to true this should mean that the Filename takes ownership of the data and will free it when it goes out of scope.
So the data is NEVER transferred to the caller. Since the caller is the one passing the data into the method. And there is no MemoryFileStruct required to use this method.
I am using this method to transfer the data, which I have allocated, into the filename. And I am setting transferownership to true so that Filename takes ownership of it so that I don't have to manage deleting it when it is out of scope. But if the documentation is correct, then I have this all backwards.
-
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
calledMemoryFileStructI
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
fortransferOwnership
toSetMemoryReadMode
, the associated memory is being freed on the deallocation of the internally usedMemoryFileStruct
. And if not, you would have to call DeleteMem(adr) yourself, whereadr
is the void pointer, you did pass intoSetMemoryReadMode
.This is further complicated by the fact that
MemoryFileStruct
is amaxon::StrongRef
tomaxon::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 ofSetMemoryReadMode
is being left. On top of that,Filename
internally now wraps aroundmaxon::Url
, its somewhat maxon API replacement, as shown in the first snippet.So, long story short, I would always pass
true
fortransferOwnership
, unless you want to cast the addressadr
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 theFilename
is really anmaxon::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 -
Thanks. The only time I pass true is when I want the memory to be deleted by the internals of the Filename. Otherwise I always leave it false since it is data I create and own. So it is doing what I expect it to which is great to know. And the docs should be updated to simply state that when true the Filename takes ownership of the data and will be deleted when it goes out of scope. The rest of the notes in that paragraph are not required.
-
Hello @kbar,
I should have replied here since there is at least an implied request in your last answer. I have added a task for this in our documentation task pool and added the tracking tag to this topic. Without any further questions or replies, we will consider this thread as solved by Monday the 20th and flag it accordingly. But that does not mean that the topic is forgotten, due to its
to fix
tag.Thank you for your understanding,
Ferdinand -