topic Re: locking handles in Archicad C++ API

locking handles

Anonymous — Mon, 07 Aug 2023 09:23:01 GMT

Hello,

I am a bit confused as to when I should lock/set handles.

From looking at some examples eg. Do_CreatePicture() in Element_Basics.cpp it looks like I should lock handles when I use them. Also in the 'About BM Manager' help file it says that BMAllocateHandle allocates a relocatable block of memory and you must use BMModifyHandle to lock a relocatable before using and unlock after!

My APX does not currently lock any handles and I've noticed that sometimes it throws an exception when I delete or change elements (both operations allocate and manipulate handles).

These things have caused me to start the long process of updating all my code so that it locks handles before using them.

What makes me unsure (and why I never considered this before) is that many examples do not lock handles before they use them.
eg.
* The ACAPI_ElementSet_Create help file
* Do_CreateLabel() in Element_Basics.cpp

Also:
* Are the handles returned from functions such as ACAPI_Element_GetMemo relocatable?

* Do I have to lock handles to access them or only to write to them.
eg. should i lock the params handle before this
if((*memo.params)[paramIndex].value.real > 0.0001)
{
}

* Do have to unlock handles before reallocating them

Thanks,
Adam

Re: locking handles

Ralph Wessel — Wed, 22 Feb 2006 23:43:15 GMT

adambutler wrote:
I am a bit confused as to when I should lock/set handles.

I can't tell you definitively about the implementation of Handles in the ArchiCAD API, but some general advice may help.

Under the Mac OS prior to Mac OS X, handles could be relocated under a wide variety of circumstances, but under Mac OS X they might only be relocated if the size is increased. Therefore, locking handles is redundant in many cases.

It has always been safe to read a value from a handle by double dereferencing the address, on the assumption that nothing could possibly occur to relocate the handle in the interim.

My practice is to be cautious and lock handles before accessing data, particularly because I often work with a pointer which is the dereferenced handle address. If the block was to be relocated, the pointer would be invalidated. A locked handle should be unlocked to avoid subsequent problems on the Mac OS.

Re: locking handles

Andras Babos — Thu, 23 Feb 2006 14:37:46 GMT

Hi!

Actually, the usage of handle locks is deprecated - as in "not needed anymore". It's only there for compatibility's sake (it does nothing, but you don't have to modify your existing codes).

So feel free to get rid of them.

HTH:
Andras.