*************************
Basic inter-process locks
*************************

The zc.lockfile package provides a basic portable implementation of
interprocess locks using lock files.  The purpose if not specifically
to lock files, but to simply provide locks with an implementation
based on file-locking primitives.  Of course, these locks could be
used to mediate access to *other* files.  For example, the ZODB file
storage implementation uses file locks to mediate access to
file-storage database files.  The database files and lock file files
are separate files.

.. contents::

Detailed Documentation
**********************

Lock file support
=================

The ZODB lock_file module provides support for creating file system
locks.  These are locks that are implemented with lock files and
OS-provided locking facilities.  To create a lock, instantiate a
LockFile object with a file name:

    >>> import zc.lockfile
    >>> lock = zc.lockfile.LockFile('lock')

If we try to lock the same name, we'll get a lock error:

    >>> import zope.testing.loggingsupport
    >>> handler = zope.testing.loggingsupport.InstalledHandler('zc.lockfile')
    >>> try:
    ...     zc.lockfile.LockFile('lock')
    ... except zc.lockfile.LockError:
    ...     print("Can't lock file")
    Can't lock file

    >>> for record in handler.records: # doctest: +ELLIPSIS
    ...     print(record.levelname+' '+record.getMessage())
    ERROR Error locking file lock; pid=...

To release the lock, use it's close method:

    >>> lock.close()

The lock file is not removed.  It is left behind:

    >>> import os
    >>> os.path.exists('lock')
    True

Of course, now that we've released the lock, we can create it again:

    >>> lock = zc.lockfile.LockFile('lock')
    >>> lock.close()

.. Cleanup

    >>> import os
    >>> os.remove('lock')


Change History
***************

1.1.0 (2013-02-12)
==================

- Added Trove classifiers and made setup.py zest.releaser friendly.

- Added Python 3.2, 3.3 and PyPy 1.9 support.

- Removed Python 2.4 and Python 2.5 support.


1.0.2 (2012-12-02)
==================

- Fixed: the fix included in 1.0.1 caused multiple pids to be written
  to the lock file


1.0.1 (2012-11-30)
==================

- Fixed: when there was lock contention, the pid in the lock file was
  lost.

  Thanks to Daniel Moisset reporting the problem and providing a fix
  with tests.

- Added test extra to declare test dependency on ``zope.testing``.

- Using Python's ``doctest`` module instead of depreacted
  ``zope.testing.doctest``.


1.0.0 (2008-10-18)
==================

- Fixed a small bug in error logging.

1.0.0b1 (2007-07-18)
====================

Initial release

Download
**********************
