Name
    IPC::SRLock - Set/reset locking semantics to single thread processes

Version
    0.1.$Revision: 45 $

Synopsis
       use IPC::SRLock;

       my $config   = { tempdir => q(path_to_tmp_directory), type => q(fcntl) };

       my $lock_obj = IPC::SRLock->new( $config );

       $lock_obj->set( k => q(some_resource_identfier) );

       # This critical region of code is guaranteed to be single threaded

       $lock_obj->reset( k => q(some_resource_identfier) );

Description
    Provides set/reset locking methods which will force a critical region of
    code to run single threaded

Subroutines/Methods
  new
    Implements the singleton pattern. The type attribute determines which
    factory subclass is loaded. This package contains three subclasses;
    fcntl, memcached and sysv

   fcntl
    Uses Fcntl to lock access to a disk based file which is read/written by
    XML::Simple. This is the default type. Files are in tempdir which
    defaults to */tmp*

   memcached
    Uses Cache::Memcached to implement a distributed lock manager. The
    servers attribute defaults to *localhost:11211*

   sysv
    Uses System V semaphores to lock access to a shared memory file

  catch
    Expose the "catch" method in IPC::SRLock::ExceptionClass

  clear_lock_obj
    Sets the internal variable that holds the self referential object to
    false. This lets the test script create multiple lock objects with
    different factory subclasses

  get_table
    Returns a hash ref that contains the current lock table contents. The
    keys/values in the hash are suitable for passing to HTML::FormWidgets

  list
    Returns an array of hash refs that represent the current lock table

  reset
    Resets the lock referenced by the k attribute.

  set
    Sets the specified lock. Attributes are:

    k  Unique key to identify the lock. Mandatory no default

    p  Explicitly set the process id associated with the lock. Defaults to
       the current process id

    t  Set the time to live for this lock. Defaults to five minutes. Setting
       it to zero makes the lock last indefinitely

  table_view
       $lock_obj->table_view( $stash, $model );

    The $model object's methods store the result of calling
    "$lock_obj->get_table" on the $stash hash ref

  throw
    Expose the "throw" method in "IPC::SRLock::ExceptionClass"

  timeout_error
    Return the text of the the timeout message

  _arg_list
       my $args = $me->_arg_list( @rest );

    Returns a hash ref containing the passed parameter list. Enables methods
    to be called with either a list or a hash ref as it's input parameters

  _ensure_class_loaded
       $me->_ensure_class_loaded( $some_class );

    Require the requested class, throw an error if it doesn't load

  _hash_merge
       my $hash = $me->_hash_merge( { key1 => val1 }, { key2 => val2 } );

    Simplistic merging of two hashes

  _init
    Called by the constructor. Optionally overridden in the factory
    subclass. This allows subclass specific initialisation

  _list
    Should be overridden in the factory subclass

  _reset
    Should be overridden in the factory subclass

  _set
    Should be overridden in the factory subclass

Diagnostics
    Setting "$app->debug" to true will cause the "set" methods to log the
    lock record at the debug level, calls "$app->log->debug"

Configuration and Environment
    None

Dependencies
    Cache::Memcached
    Class::Accessor::Fast
    Class::Inspector
    Class::Null
    Date::Format
    IO::AtomicFile
    IO::File
    IPC::SRLock::ExceptionClass
    IPC::SysV
    Readonly
    Time::Elapsed
    Time::HiRes
    XML::Simple

Incompatibilities
    The sysv subclass will not work on cygwin

Bugs and Limitations
    Testing of the memcached subclass is skipped on all platforms as it
    requires "memcached" to be listening on the localhost's default
    memcached port *localhost:11211*

    Automated testing has been disabled due to inconsistancies in the CPAN
    testing platforms. See spurious results on previous releases

    There are no known bugs in this module. Please report problems to the
    address below. Patches are welcome

Author
    Peter Flanigan, "<Support at RoxSoft.co.uk>"

License and Copyright
    Copyright (c) 2008 Peter Flanigan. All rights reserved

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself. See perlartistic

    This program is distributed in the hope that it will be useful, but
    WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE