29 Sep 2017 02:17:12 UTC
- Distribution: Patro
- Module version: 0.16
- Source (raw)
- Browse (raw)
- How to Contribute
- Issues (1)
- Testers (406 / 59 / 25)
- KwaliteeBus factor: 1
- % Coverage
- License: perl_5
- Activity24 month
- Download (53.83KB)
- MetaCPAN Explorer
- Subscribe to distribution
- This version
- Latest versionMOB Marty O'Brien
- LICENSE AND COPYRIGHT
Patro::Archy - establish norms about exclusive access to references
At times we want threads and processes to have exclusive access to some resources, even if they have to wait for it. The
Patro::Archyprovides 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::Archyall 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.
Attempts to acquire an exclusive (but advisory) lock on the reference given by
$objectfor a monitor identified by
$id. Returns true if the lock was successfully acquired.
The monitor id
$idis 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
$timeoutargument is provided, the function will give up trying to acquire the lock and return false after
$timeoutis 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
plockfor 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
plockon a reference (or provide a
$countargument to "punlock") before it will be released.
Releases the lock on reference
$objectheld 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
$countargument, if provided, will apply the unlock operation
$counttimes. 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
$countargument will release control of the reference unconditionally.
Releases the lock on reference
$objectand 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
$timeoutis specified and it takes longer than
$timeoutseconds to acquire the lock.
Causes one or more (depending whether
$countis 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.
Currently only works on systems that have a shared-memory virtual filesystem in
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.