Weird PF_Handle declaration in Adobe After Effects SDK

Question

I 'm trying to host After Effects plugins in my video editor.

On implementing some of the Adobe Callbacks, there 's a suite (a set of function pointers) that allocate memory, of type PF_Handle. This type has a weird declaration of typedef void **PF_Handle;

A double pointer. The function pointers I am requested to implement are described here.

PF_Handle (*host_new_handle)(A_HandleSize size);
void (*host_lock_handle)(PF_Handle pf_handle);
void (*host_unlock_handle)(PF_Handle pf_handle);
void (*host_dispose_handle)(PF_Handle pf_handle);

Nothing would be weird if the PF_Handle was a plain void*, I would simply call new/delete and cast the pointer. Indeed, the same plugin's code I am debugging takes that pointer, locks it, and uses it directly. But in the very same plugin later,I see code like this:

`return *(PF_Pixel**)m_bufH;`

m_bufH is PF_Handle which was allocated by a call to host_new_handle. This means that the plugin expects a double pointer. No locking function is called and the plugin attemps to access the double pointer data, failing of course.

What could be the issue?

What could happen here? What's the meaning of locking and unlocking a double pointer?

Answer 1

A handle points to movable memory. The memory may be moved by the memory manager, invalidating the pointer you have. In order to create a handle, use the API provided by the memory manager — otherwise the manager will not know how to move the allocated memory. Locking the handle protects the memory from being used and gives you a pointer you can use while the handle is locked. You should not keep handles locked longer than strictly necessary to access the memory, otherwise you defy the purpose of the memory manager, causing resource depletion and other problems. Accessing an unlocked handle through a double dereference is possible under condition that the compiler does not optimise it out. And it is slower than locking, unless you do just one simple thing.