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([dnl
The Lock subsystem is useful outside the context of m4_db.  It can be
used to manage concurrent access to any collection of either ephemeral
or persistent objects.  That is, the lock region can persist across
invocations of an application, so it can be used to provide long-term
locking (for example, conference room scheduling).])

m4_p([dnl
In order to use the locking subsystem in such a general way, the
applications must adhere to a convention for identifying objects and
lockers.  Consider a conference room scheduling problem, in which there
are three conference rooms scheduled in half-hour intervals. The
scheduling application must then select a way to identify each
conference room/time slot combination.  In this case, we could describe
the objects being locked as bytestrings consisting of the conference
room name, the date when it is needed, and the beginning of the
appropriate half-hour slot.])

m4_p([dnl
Lockers are 32-bit numbers, so we might choose to use the User ID of
the individual running the scheduling program.  To schedule half-hour
slots, all the application needs to do is issue a m4_ref(lock_get) call
for the appropriate locker/object pair.  To schedule a longer slot, the
application needs to issue a m4_ref(lock_vec) call, with one
m4_ref(lock_get) operation per half-hour -- up to the total length.  If
the m4_ref(lock_vec) call fails, the application would have to release
the parts of the time slot that were obtained.])

m4_p([dnl
To cancel a reservation, the application would make the appropriate
m4_ref(lock_put) calls.  To reschedule a reservation, the
m4_ref(lock_get) and m4_ref(lock_put) calls could all be made inside of
a single m4_ref(lock_vec) call.  The output of m4_ref(lock_stat) could
be post-processed into a human-readable schedule of conference room
use.])

m4_page_footer