(v13) RDR Example: RDR iteration
This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP
In addition to finding an RDR by Class, Type and ID using SwFindRDR
or by Namespace, Name and ID using SwFindNamedRDR
(which may or may not succeed, depending on registrations), a consumer can also search through registered RDRs by Class and Type or by Namespace and Name.
The consumer calls SwFindRDRbyType
or SwFindNamedRDRbyName
to create an Iterator. It then calls SwNextRDR
repeatedly using that Iterator until that fails to return a matching RDR, and finally finishes with the Iterator by calling SwFoundRDR
.
If such a search is a common occurrence, the consumer may choose to use a persistent Iterator. SwFindRDRbyType
or SwFindNamedRDRbyName
can be called long in advance of the search to create the Iterator. Once a search has completed it can call SwRestartFindRDR
to return the Iterator to its initialized state ready for another search. Once finished with, SwFoundRDR
must still be called to delete the Iterator.
Care must be taken in a multi-threaded system such as Harlequin RIP. It is theoretically possible for an RDR to be de-registered by some other thread between a call to SwNextRDR
returning that RDR and the consumer using it. Using SwLockNextRDR
instead of SwNextRDR
avoids this possibility by locking the RDR returned to prevent it being deregistered. It remains locked until the consumer calls SwLockNextRDR
again, or any of SwNextRDR
, SwFoundRDR
or SwRestartFindRDR
.
If SwDeregisterRDR
or SwDeregisterNamedRDR
is called on a locked RDR it is deregistered at once to prevent further discovery but is only discarded once fully unlocked. Also note that multiple separate find operations could have locked the RDR many times, and all must unlock before the RDR is finally discarded.
A supplier which calls SwDeregisterRDR
or SwDeregisterNamedRDR
because it intends to discard the entity in question must therefore be prepared for that call to return SW_RDR_ERROR_IN_USE, indicating that the RDR has been locked, and retry the deregistration until that error is no longer returned, indicating the consumers have moved on to other RDRs. Only then is it safe to discard the entity in question. Obviously, if ROM data was registered this is less of a concern, but structures constructed in a memory allocation that is to be freed cannot be whilst still in use.
Suppliers are encouraged to avoid blocking after SW_RDR_ERROR_IN_USE has been returned unless absolutely necessary.