~bzr-pqm/bzr/bzr.dev : contents of bzrlib/inter.py at revision 1551.8.17

~bzr-pqm/bzr/bzr.dev : (revision 1551.8.17)

# Copyright (C) 2006 Canonical Ltd
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


"""Inter-object utility class."""


class InterObject(object):
    """This class represents operations taking place between two objects.

    Its instances have methods like join or copy_content or fetch, and contain
    references to the source and target objects these operations can be 
    carried out between.

    Often we will provide convenience methods on the objects which carry out
    operations with another of similar type - they will always forward to
    a subclass of InterObject - i.e. 
    InterVersionedFile.get(other).method_name(parameters).

    If the source and target objects implement the locking protocol - 
    lock_read, lock_write, unlock, then the InterObject's lock_read,
    lock_write and unlock methods may be used (optionally in conjunction with
    the needs_read_lock and needs_write_lock decorators.)
    """

    # _optimisers = set()
    # Each concrete InterObject type should have its own optimisers set.

    def __init__(self, source, target):
        """Construct a default InterObject instance. Please use 'get'.
        
        Only subclasses of InterObject should call 
        InterObject.__init__ - clients should call InterFOO.get where FOO
        is the base type of the objects they are interacting between. I.e.
        InterVersionedFile or InterRepository.
        get() is a convenience class method which will create an optimised
        InterFOO if possible.
        """
        self.source = source
        self.target = target

    def _double_lock(self, lock_source, lock_target):
        """Take out two locks, rolling back the first if the second throws."""
        lock_source()
        try:
            lock_target()
        except Exception:
            # we want to ensure that we don't leave source locked by mistake.
            # and any error on target should not confuse source.
            self.source.unlock()
            raise

    @classmethod
    def get(klass, source, target):
        """Retrieve a Inter worker object for these objects.

        :param source: the object to be the 'source' member of
                       the InterObject instance.
        :param target: the object to be the 'target' member of
                       the InterObject instance.
        If an optimised worker exists it will be used otherwise
        a default Inter worker instance will be created.
        """
        for provider in klass._optimisers:
            if provider.is_compatible(source, target):
                return provider(source, target)
        return klass(source, target)

    def lock_read(self):
        """Take out a logical read lock.

        This will lock the source branch and the target branch. The source gets
        a read lock and the target a read lock.
        """
        self._double_lock(self.source.lock_read, self.target.lock_read)

    def lock_write(self):
        """Take out a logical write lock.

        This will lock the source branch and the target branch. The source gets
        a read lock and the target a write lock.
        """
        self._double_lock(self.source.lock_read, self.target.lock_write)

    @classmethod
    def register_optimiser(klass, optimiser):
        """Register an InterObject optimiser."""
        klass._optimisers.add(optimiser)

    def unlock(self):
        """Release the locks on source and target."""
        try:
            self.target.unlock()
        finally:
            self.source.unlock()

    @classmethod
    def unregister_optimiser(klass, optimiser):
        """Unregister an InterObject optimiser."""
        klass._optimisers.remove(optimiser)

1563.2.12 by Robert Collins Checkpointing: created InterObject to factor out common inter object worker code, added InterVersionedFile and tests to allow making join work between any versionedfile.	1	# Copyright (C) 2006 Canonical Ltd
	2	#
	3	# This program is free software; you can redistribute it and/or modify
	4	# it under the terms of the GNU General Public License as published by
	5	# the Free Software Foundation; either version 2 of the License, or
	6	# (at your option) any later version.
	7	#
	8	# This program is distributed in the hope that it will be useful,
	9	# but WITHOUT ANY WARRANTY; without even the implied warranty of
	10	# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	11	# GNU General Public License for more details.
	12	#
	13	# You should have received a copy of the GNU General Public License
	14	# along with this program; if not, write to the Free Software
	15	# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
	16
	17
	18	"""Inter-object utility class."""
	19
	20
	21	class InterObject(object):
	22	"""This class represents operations taking place between two objects.
	23
	24	Its instances have methods like join or copy_content or fetch, and contain
	25	references to the source and target objects these operations can be
	26	carried out between.
	27
	28	Often we will provide convenience methods on the objects which carry out
	29	operations with another of similar type - they will always forward to
	30	a subclass of InterObject - i.e.
	31	InterVersionedFile.get(other).method_name(parameters).
1852.11.1 by Robert Collins Deprecate compare_trees and move its body to InterTree.changes_from.	32
	33	If the source and target objects implement the locking protocol -
	34	lock_read, lock_write, unlock, then the InterObject's lock_read,
	35	lock_write and unlock methods may be used (optionally in conjunction with
	36	the needs_read_lock and needs_write_lock decorators.)
1563.2.12 by Robert Collins Checkpointing: created InterObject to factor out common inter object worker code, added InterVersionedFile and tests to allow making join work between any versionedfile.	37	"""
	38
	39	# _optimisers = set()
	40	# Each concrete InterObject type should have its own optimisers set.
	41
	42	def __init__(self, source, target):
	43	"""Construct a default InterObject instance. Please use 'get'.
	44
	45	Only subclasses of InterObject should call
	46	InterObject.__init__ - clients should call InterFOO.get where FOO
	47	is the base type of the objects they are interacting between. I.e.
	48	InterVersionedFile or InterRepository.
	49	get() is a convenience class method which will create an optimised
	50	InterFOO if possible.
	51	"""
	52	self.source = source
	53	self.target = target
	54
1852.11.1 by Robert Collins Deprecate compare_trees and move its body to InterTree.changes_from.	55	def _double_lock(self, lock_source, lock_target):
1852.11.3 by Robert Collins Fix typo in inter.py.	56	"""Take out two locks, rolling back the first if the second throws."""
1852.11.1 by Robert Collins Deprecate compare_trees and move its body to InterTree.changes_from.	57	lock_source()
	58	try:
	59	lock_target()
	60	except Exception:
	61	# we want to ensure that we don't leave source locked by mistake.
	62	# and any error on target should not confuse source.
	63	self.source.unlock()
	64	raise
	65
1563.2.12 by Robert Collins Checkpointing: created InterObject to factor out common inter object worker code, added InterVersionedFile and tests to allow making join work between any versionedfile.	66	@classmethod
	67	def get(klass, source, target):
	68	"""Retrieve a Inter worker object for these objects.
	69
	70	:param source: the object to be the 'source' member of
	71	the InterObject instance.
	72	:param target: the object to be the 'target' member of
	73	the InterObject instance.
	74	If an optimised worker exists it will be used otherwise
	75	a default Inter worker instance will be created.
	76	"""
	77	for provider in klass._optimisers:
	78	if provider.is_compatible(source, target):
	79	return provider(source, target)
	80	return klass(source, target)
	81
1852.11.1 by Robert Collins Deprecate compare_trees and move its body to InterTree.changes_from.	82	def lock_read(self):
	83	"""Take out a logical read lock.
	84
	85	This will lock the source branch and the target branch. The source gets
	86	a read lock and the target a read lock.
	87	"""
	88	self._double_lock(self.source.lock_read, self.target.lock_read)
	89
	90	def lock_write(self):
	91	"""Take out a logical write lock.
	92
	93	This will lock the source branch and the target branch. The source gets
	94	a read lock and the target a write lock.
	95	"""
	96	self._double_lock(self.source.lock_read, self.target.lock_write)
	97
1563.2.12 by Robert Collins Checkpointing: created InterObject to factor out common inter object worker code, added InterVersionedFile and tests to allow making join work between any versionedfile.	98	@classmethod
	99	def register_optimiser(klass, optimiser):
	100	"""Register an InterObject optimiser."""
	101	klass._optimisers.add(optimiser)
	102
1852.11.1 by Robert Collins Deprecate compare_trees and move its body to InterTree.changes_from.	103	def unlock(self):
	104	"""Release the locks on source and target."""
	105	try:
	106	self.target.unlock()
	107	finally:
	108	self.source.unlock()
	109
1563.2.12 by Robert Collins Checkpointing: created InterObject to factor out common inter object worker code, added InterVersionedFile and tests to allow making join work between any versionedfile.	110	@classmethod
	111	def unregister_optimiser(klass, optimiser):
	112	"""Unregister an InterObject optimiser."""
	113	klass._optimisers.remove(optimiser)