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