NAME
Patro::Archy - establish norms about exclusive access to references
DESCRIPTION
At times we want threads and processes to have exclusive access to some resources, even if they have to wait for it. The Patro::Archy provides functions to request exclusive access to a resource and to relinquish control of the resource. It also implements an additional wait/notify feature.
The functions of Patro::Archy all take the same two first arguments: a reference -- the resource that will be used exclusively in one thread or process, and an id that uniquely identifies a thread or process that seeks exclusive access to a resource.
Like most such locks in Perl, the locks from this package are advisory -- they can only prevent access to the resource from other threads and processes that use the same locking scheme.
FUNCTIONS
plock
$status = plock($object, $id [, $timeout])
Attempts to acquire an exclusive (but advisory) lock on the reference given by $object for a monitor identified by $id. Returns true if the lock was successfully acquired.
The monitor id $id is an arbitrary string that identifies the thread or process that seeks to acquire the resource. In this function and in the other public functions of Patro::Archy, there is an implementation limitation that the monitor id be no more than 20 characters.
If a positive $timeout argument is provided, the function will give up trying to acquire the lock and return false after $timeout seconds. If $timeout is negative, the function call will be treated as a non-blocking lock call, and the function will return as soon as it can be determined whether the lock is available.
It is acceptable to call plock for a monitor that already possesses the lock. Successive lock calls "stack", so that you must call "punlock" the same number of times that you called plock on a reference (or provide a $count argument to "punlock") before it will be released.
punlock
$status = punlock($object, $id[, $count])
Releases the lock on reference $object held by the monitor identified by $id. Returns true on success. A false return value generally means that the monitor did not have possession of the lock at the time of the punlock call.
A positive $count argument, if provided, will apply the unlock operation $count times. Since lock calls from the same monitor "stack" (see "plock"), it may be necessary to apply the unlock operation more than once to release control of the reference. A negative $count argument will release control of the reference unconditionally.
pwait
$status = pwait($object, $id [, $timeout])
Releases the lock on reference $object and waits for the "pnotify" function to be called from another monitor. After the "pnotify" call is received by the monitor, the monitor will attempt to acquire the lock on the resource again. The monitor is only supposed to call this function when it is in possession of the lock.
Returns true after the lock has been successfully acquired. Returns false if the function is called while the monitor does not have the lock on the resource, or if $timeout is specified and it takes longer than $timeout seconds to acquire the lock.
pnotify
$status = pnotify($object, $id [, $count])
Causes one or more (depending whether $count is specified) monitors that have previously called "pwait" to wake up and attempt to reacquire the lock on the resource. The monitor is supposed to call this function while it is in possession of the lock. Note that this call does not release the resource. Returns true on success.
LIMITATIONS
Currently only works on systems that have a shared-memory virtual filesystem in /dev/shm.
LICENSE AND COPYRIGHT
MIT License
Copyright (c) 2017, Marty O'Brien
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.