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 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

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