From: Mukund Sivaraman Date: Wed, 10 Jul 2013 11:42:02 +0000 (+0530) Subject: [2856] Add documentation X-Git-Tag: bind10-1.2.0beta1-release~306^2~18 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2de17f71bab2fe5b02ca8563477441dc2805661c;p=thirdparty%2Fkea.git [2856] Add documentation --- diff --git a/src/lib/python/isc/memmgr/datasrc_info.py b/src/lib/python/isc/memmgr/datasrc_info.py index c7ad598675..845e11358a 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)