Property :: lockCollection - Lock collection
In order to prevent other applications accessing a collection managed by the property handle, this function allows locking the collection. As long as the collection is locked no other process or thread is able to lock the collection. Locking a collection protects the collection from being read or updated.
Locking a collection twice in the same or another application will fail (returns false). Collections locked have to be unlocked explicitly. Closing the property handle does not unlock the collection. Locks are reset when closing the database or terminating the application.
Locked collections can be unlocked by calling unlockCollection().
The function returns true, when locking succeeded and false, when the collection is already locked. The function must not be called from within context class event handlers, which will cause an exception. The function also throws an exception, when the property does not handle a collection or when no instance is selected in the parent property handle or property handle is invalid.
This feature is dangerous, since remaining locks (e.g. because improper exception handling may cause system dead locks. Hence, we suggest using locker classes (like CollectionLock) instaed, which are automatically destructed when leaving the function, which will unlock the locked resource.
Nevertheless, lock functions might be used, when lock and unlock are called in different functions, which cannot be avoided, sometimes.
The value is true when the function was executed successfully. Otherwise the value is set to false.
Implementation overview
- Lock collection immediately
Property :: lockCollection ( ) - Lock and wait
Property :: lockCollection ( iTimeout )
Implementation details
- to list
-
Lock and wait
bool Property :: lockCollection ( int32 iTimeout )
The function locks the collection and waits the number of seconds passed in iTimeout, when the collection is not available. The function returns true, as soon as the collection could be locked. When the waiting interval has passed without being able to lock the collection, the function returns false.
- iTimeout - Timeout in seconds
to list