m4_comment([$Id: nondb.so,v 10.15 2001/05/22 19:39:31 bostic Exp $])m4_ref_title(Locking Subsystem,    Locking and non-m4_db applications,    @locking and non-m4_db applications, lock/am_conv, log/intro)m4_p([dnlThe Lock subsystem is useful outside the context of m4_db.  It can beused to manage concurrent access to any collection of either ephemeralor persistent objects.  That is, the lock region can persist acrossinvocations of an application, so it can be used to provide long-termlocking (for example, conference room scheduling).])m4_p([dnlIn order to use the locking subsystem in such a general way, theapplications must adhere to a convention for identifying objects andlockers.  Consider a conference room scheduling problem, in which thereare three conference rooms scheduled in half-hour intervals. Thescheduling application must then select a way to identify eachconference room/time slot combination.  In this case, we could describethe objects being locked as bytestrings consisting of the conferenceroom name, the date when it is needed, and the beginning of theappropriate half-hour slot.])m4_p([dnlLockers are 32-bit numbers, so we might choose to use the User ID ofthe individual running the scheduling program.  To schedule half-hourslots, all the application needs to do is issue a m4_ref(lock_get) callfor the appropriate locker/object pair.  To schedule a longer slot, theapplication needs to issue a m4_ref(lock_vec) call, with onem4_ref(lock_get) operation per half-hour -- up to the total length.  Ifthe m4_ref(lock_vec) call fails, the application would have to releasethe parts of the time slot that were obtained.])m4_p([dnlTo cancel a reservation, the application would make the appropriatem4_ref(lock_put) calls.  To reschedule a reservation, them4_ref(lock_get) and m4_ref(lock_put) calls could all be made inside ofa single m4_ref(lock_vec) call.  The output of m4_ref(lock_stat) couldbe post-processed into a human-readable schedule of conference roomuse.])m4_page_footer