BIND 10 trac2856, updated. 2de17f71bab2fe5b02ca8563477441dc2805661c [2856] Add documentation
BIND 10 source code commits
bind10-changes at lists.isc.org
Wed Jul 10 11:55:16 UTC 2013
The branch, trac2856 has been updated
via 2de17f71bab2fe5b02ca8563477441dc2805661c (commit)
from 644a03f0da719b01456ea0115cc0bd661ff9e636 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 2de17f71bab2fe5b02ca8563477441dc2805661c
Author: Mukund Sivaraman <muks at isc.org>
Date: Wed Jul 10 17:12:02 2013 +0530
[2856] Add documentation
-----------------------------------------------------------------------
Summary of changes:
src/lib/python/isc/memmgr/datasrc_info.py | 70 ++++++++++++++++++++++++++---
1 file changed, 64 insertions(+), 6 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/python/isc/memmgr/datasrc_info.py b/src/lib/python/isc/memmgr/datasrc_info.py
index c7ad598..845e113 100644
--- a/src/lib/python/isc/memmgr/datasrc_info.py
+++ b/src/lib/python/isc/memmgr/datasrc_info.py
@@ -43,30 +43,62 @@ class SegmentInfo:
READER = 0
WRITER = 1
- # Enumerated values for state
- UPDATING = 0
- SYNCHRONIZING = 1
- COPYING = 2
- READY = 3
+ # Enumerated values for state:
+ UPDATING = 0 # the segment is being updated (by the builder thread,
+ # although SegmentInfo won't care about this level of
+ # details).
+ SYNCHRONIZING = 1 # one pair of underlying segments has been
+ # updated, and readers are now migrating to the
+ # updated version of the segment.
+ COPYING = 2 # all readers that used the old version of segment have
+ # been migrated to the updated version, and the old
+ # segment is now being updated.
+ READY = 3 # both segments of the pair have been updated. it can now
+ # handle further updates (e.g., from xfrin).
def __init__(self):
self.__state = self.READY
+ # __readers is a set of 'reader_session_id' private to
+ # SegmentInfo. It consists of the (ID of) reader modules that
+ # are using the "current" reader version of the segment.
self.__readers = set()
+ # __old_readers is a set of 'reader_session_id' private to
+ # SegmentInfo for write (update), but publicly readable. It can
+ # be non empty only in the SYNCHRONIZING state, and consists of
+ # (ID of) reader modules that are using the old version of the
+ # segments (and have to migrate to the updated version).
self.__old_readers = set()
+ # __events is a FIFO queue of opaque data for pending update
+ # events. Update events can come at any time (e.g., after
+ # xfr-in), but can be only handled if SegmentInfo is in the
+ # READY state. This maintains such pending events in the order
+ # they arrived. SegmentInfo doesn't have to know the details of
+ # the stored data; it only matters for the memmgr.
self.__events = []
def get_state(self):
+ """Returns the state of SegmentInfo (UPDATING, SYNCHRONIZING,
+ COPYING or READY)."""
return self.__state
def get_readers(self):
+ """Returns a set of IDs of the reader modules that are using the
+ "current" reader version of the segment. This method is mainly
+ useful for testing purposes."""
return self.__readers
def get_old_readers(self):
+ """Returns a set of IDs of reader modules that are using the old
+ version of the segments and have to be migrated to the updated
+ version."""
return self.__old_readers
def get_events(self):
+ """Returns a list of pending events in the order they arrived."""
return self.__events
+ # Helper method used in complete_update(), sync_reader() and
+ # remove_reader().
def __sync_reader_helper(self, new_state):
if len(self.__old_readers) == 0:
self.__state = new_state
@@ -78,9 +110,20 @@ class SegmentInfo:
return None
def add_event(self, event_data):
+ """Add an event to the end of the pending events queue. The
+ event_data is not used internally by this class, and is returned
+ as-is by other methods. The format of event_data only matters in
+ the memmgr. This method must be called by memmgr when it
+ receives a request for reloading a zone. No state transition
+ happens."""
self.__events.append(event_data)
def add_reader(self, reader_session_id):
+ """Add the reader module ID to an internal set of reader modules
+ that are using the "current" reader version of the segment. It
+ must be called by memmgr when it first gets the pre-existing
+ readers or when it's notified of a new reader. No state
+ transition happens."""
if reader_session_id in self.__readers:
raise SegmentInfoError('Reader session ID is already in readers set: ' +
str(reader_session_id))
@@ -88,13 +131,28 @@ class SegmentInfo:
self.__readers.add(reader_session_id)
def start_update(self):
- if self.__state == self.READY and len(self.__events) > 0:
+ """If the current state is READY and there are pending events,
+ it changes the state to UPDATING and returns the head (oldest)
+ event (without removing it from the pending events queue). This
+ tells the caller (memmgr) that it should initiate the update
+ process with the builder. In all other cases it returns None."""
+ if self.__state == self.READY and len(self.__events) > 0:
self.__state = self.UPDATING
return self.__events[0]
return None
def complete_update(self):
+ """This method should be called when memmgr is notified by the
+ builder of the completion of segment update. It changes the
+ state from UPDATING to SYNCHRONIZING, and COPYING to READY. In
+ the former case, set of reader modules that are using the
+ "current" reader version of the segment are moved to the set
+ that are using an "old" version of segment. If there are no such
+ readers using the "old" version of segment, it pops the head
+ (oldest) event from the pending events queue and returns it. It
+ is an error if this method is called in other states than
+ UPDATING and COPYING."""
if self.__state == self.UPDATING:
self.__state = self.SYNCHRONIZING
self.__old_readers.update(self.__readers)
More information about the bind10-changes
mailing list