Loading

interfaces.py

  1. #!/usr/bin/env python
  2.  
  3. from __future__ import (
  4.     generators, division, absolute_import, with_statement, print_function
  5. )
  6.  
  7. from zope.interface import Interface, Attribute
  8.  
  9.  
  10. class IPeerSelector(Interface):
  11.     """
  12.    I select peers for an upload, maximizing some measure of health.
  13.  
  14.    I keep track of the state of a grid relative to a file. This means
  15.    that I know about all of the peers that parts of that file could be
  16.    placed on, and about shares that have been placed on those peers.
  17.    Given this, I assign shares to peers in a way that maximizes the
  18.    file's health according to whichever definition of health I am
  19.    programmed with. I tell the uploader whether or not my assignment is
  20.    healthy. I keep track of failures during the process and update my
  21.    conclusions appropriately.
  22.    """
  23.     def add_peer_with_share(peerid, shnum):
  24.         """
  25.        Update my internal state to reflect the fact that peer peerid
  26.        holds share shnum. Called for shares that are detected before
  27.        peer selection begins.
  28.        """
  29.  
  30.     def confirm_share_allocation(peerid, shnum):
  31.         """
  32.        Confirm that an allocated peer=>share pairing has been
  33.        successfully established.
  34.        """
  35.  
  36.     def add_peers(peerids=set):
  37.         """
  38.        Update my internal state to include the peers in peerids as
  39.        potential candidates for storing a file.
  40.        """
  41.  
  42.     def mark_readonly_peer(peerid):
  43.         """
  44.        Mark the peer peerid as full. This means that any
  45.        peer-with-share relationships I know about for peerid remain
  46.        valid, but that peerid will not be assigned any new shares.
  47.        """
  48.  
  49.     def mark_bad_peer(peerid):
  50.         """
  51.        Mark the peer peerid as bad. This is typically called when an
  52.        error is encountered when communicating with a peer. I will
  53.        disregard any existing peer => share relationships associated
  54.        with peerid, and will not attempt to assign it any more shares.
  55.        """
  56.  
  57.     def get_share_placements():
  58.         """
  59.        Return the share-placement map (a dict) which maps shares to
  60.        server-ids
  61.        """
  62.  
  63.  
  64. class IPeerSelector2Factory(Interface):
  65.     """
  66.    Creates IPeerSelector2 instance.
  67.    """
  68.     def __call__(total_shares, potential_peers=(), preferred_peers=()):
  69.         """
  70.        Initialize PeerSelector instance
  71.        """
  72.  
  73.  
  74. class IPeerSelector2(Interface):
  75.     """
  76.    I select peers for an upload, maximizing some measure of health.
  77.  
  78.    I keep track of the state of a grid relative to a file.
  79.    This means that I know about all of the peers that parts of that file could
  80.    be placed on, and about shares that have been placed on those peers.
  81.    Given this, I assign shares to peers in a way that maximizes the file's
  82.    health according to whichever definition of health I am programmed with.
  83.    I also understandand relative preferences between peers for shares to be
  84.    placed on.
  85.    I tell the uploader whether or not my assignment is healthy.
  86.    I keep track of failures during the process and update my conclusions
  87.    appropriately.
  88.    """
  89.     def iterate_peers():
  90.         """
  91.        Iterates peers in order of preference.
  92.  
  93.        Yields (IServer, bool is_readonly, bool is_preferred) triples.
  94.        Preferred peers go first, then non-preferred, in order they were listed
  95.        in potential_peers sequence.
  96.        """
  97.  
  98.     # TODO: We don't need following two methods given initialization is done
  99.     # via IPeerSelector2Factory
  100.  
  101.     # def set_potential_peers(potential_peers):
  102.     #     """
  103.     #     Set the ordered list of potential peers.
  104.     #     """
  105.  
  106.     # def mark_preferred_peer(peerid):
  107.     #     """
  108.     #     Mark peerid as a preferred peer.
  109.  
  110.     #     Preferred peers get one share allocation each (up to number of shares)
  111.     #     regardless of whether those shares already exist elsewhere.
  112.     #     """
  113.  
  114.     def add_peer_with_share(peerid, shnum):
  115.         """
  116.        Update my internal state to reflect the fact that peer peerid
  117.        holds share shnum. Called for shares that are detected before
  118.        peer selection begins.
  119.        """
  120.  
  121.     def confirm_share_allocation(peerid, shnum):
  122.         """
  123.        Confirm that an allocated peer=>share pairing has been
  124.        successfully established.
  125.        """
  126.  
  127.     def mark_readonly_peer(peerid):
  128.         """
  129.        Mark the peer peerid as full. This means that any
  130.        peer-with-share relationships I know about for peerid remain
  131.        valid, but that peerid will not be assigned any new shares.
  132.        """
  133.  
  134.     def mark_bad_peer(peerid):
  135.         """
  136.        Mark the peer peerid as bad. This is typically called when an
  137.        error is encountered when communicating with a peer. I will
  138.        disregard any existing peer => share relationships associated
  139.        with peerid, and will not attempt to assign it any more shares.
  140.        """
  141.  
  142.     def get_share_placements():
  143.         """
  144.        Return the share-placement map (a dict) which maps shares to
  145.        server-ids
  146.        """
  147.  
  148.     def get_sharemap_of_preexisting_shares():
  149.         """
  150.        Return mapping of shares to sets of servers.
  151.        """