Experience in using these functions within the other parts of the bpo_ sub-system has shown that they are not the best solution to the problem of providing sequential access to structures. They are are no longer used internally and may be removed from a later version of the library.
There are six functions in three pairs. They all take as their single parameter a pointer to a bpo_fl_lock structure.
The read lock functions
void bpo_RLock( struct bpo_fl_lock *bflp );
void bpo_RUnlock(struct bpo_fl_lock *bflp );
the write lock functions
void bpo_WLock( struct bpo_fl_lock *bflp);
void bpo_WUnlock(struct bpo_fl_lock *bflp );
and the lock change functions
int bpo_RWLock( struct bpo_fl_lock *bflp );
void bpo_WRLock( struct bpo_fl_lock *bflp );
The first four functions behave as one might expect, blocking on Lock until appropriate, and clear immediately on Unlock.
The last two functions require a little explanation. These are provided to allow an upgrade from Read lock status to Write lock status and vice-versa. For the change from Read to Write lock the function returns an integer which specifies whether the change was succesfull. It returns 1 on success, and 0 on failure.
Failure can occur if there is already a process waiting for the write lock. If the routine fails, then the application should release the read lock (which the other application is waiting for) and retry after some suitable interval to either gain a read lock and upgrade, or to obtain a write lock straight away. Regardless of which method is used, any object being refered to on the list should be searched for again, since the process that gained the write lock previously may have removed it (unless you can guarantee that this is not the case).