def __init__(self, treeConfig=None): '''The optional treeConfig is an instance of TreeConfig. A default one is created if not given. ''' self.__allTopics = None # root of topic tree self._topicsMap = {} # registry of all topics self.__treeConfig = treeConfig or TreeConfig() self.__defnProvider = MasterTopicDefnProvider(self.__treeConfig) # define root of all topics assert self.__allTopics is None argsDocs, reqdArgs = getRootTopicSpec() desc = 'Root of all topics' specGiven = ArgSpecGiven(argsDocs, reqdArgs) self.__allTopics = self.__createTopic((ALL_TOPICS,), desc, specGiven=specGiven)
class TopicManager: ''' Manages the registry of all topics and creation/deletion of topics. Note that all methods that start with an underscore are part of the private API. ''' # Allowed return values for isTopicSpecified() TOPIC_SPEC_NOT_SPECIFIED = 0 # false TOPIC_SPEC_ALREADY_CREATED = 1 # all other values equate to "true" but different reason TOPIC_SPEC_ALREADY_DEFINED = 2 def __init__(self, treeConfig=None): '''The optional treeConfig is an instance of TreeConfig. A default one is created if not given. ''' self.__allTopics = None # root of topic tree self._topicsMap = {} # registry of all topics self.__treeConfig = treeConfig or TreeConfig() self.__defnProvider = MasterTopicDefnProvider(self.__treeConfig) # define root of all topics assert self.__allTopics is None argsDocs, reqdArgs = getRootTopicSpec() desc = 'Root of all topics' specGiven = ArgSpecGiven(argsDocs, reqdArgs) self.__allTopics = self.__createTopic((ALL_TOPICS,), desc, specGiven=specGiven) def getRootTopic(self): '''Get root topic of topic tree. This is the pub.ALL_TOPICS topic, it receives messages for all topics.''' return self.__allTopics def addDefnProvider(self, provider): '''Register provider as topic specification provider. Whenever a topic must be created, the first provider that has a specification for the created topic is used to initialize the topic. The given provider must be an object that has a getDescription(topicNameTuple) and getArgs(topicNameTuple) that return a description string and a pair (argsDocs, requiredArgs), respectively. Note that Nothing is done if provider already added. Returns how many providers have been registered, ie if new provider, will be 1 + last call's return, otherwise (provider had already been added) will be same as last call's return value.''' return self.__defnProvider.addProvider(provider) def clearDefnProviders(self): '''Remove all registered topic specification providers''' self.__defnProvider.clear() def getNumDefnProviders(self): return self.__defnProvider.getNumProviders() def getTopic(self, name, okIfNone=False): '''Get the Topic instance that corresponds to the given topic name path. By default, raises an UndefinedTopic or UndefinedSubtopic exception if a topic with given name doesn't exist. If okIfNone=True, returns None instead of raising an exception.''' topicNameDotted = stringize(name) #if not name: # raise TopicNameInvalid(name, 'Empty topic name not allowed') obj = self._topicsMap.get(topicNameDotted, None) if obj is not None: return obj if okIfNone: return None # NOT FOUND! Determine what problem is and raise accordingly: # find the closest parent up chain that does exists: parentObj, subtopicNames = self.__getClosestParent(topicNameDotted) assert subtopicNames subtopicName = subtopicNames[0] if parentObj is self.__allTopics: raise UndefinedTopic(subtopicName) raise UndefinedSubtopic(parentObj.getName(), subtopicName) def newTopic(self, _name, _desc, _required=(), **_argDocs): '''Legacy method, kept for backwards compatibility. If topic _name already exists, just returns it and does nothing else. Otherwise, use getOrCreateTopic() to create it, then set its description (_desc) and its listener specification (_argDocs and _required). See getOrCreateTopic() for info on the listener spec.''' topic = self.getTopic(_name, True) if topic is None: topic = self.getOrCreateTopic(_name) topic.setDescription(_desc) topic.setMsgArgSpec(_argDocs, _required) return topic def getOrCreateTopic(self, name, protoListener=None): '''Get the topic object for topic of given name, creating it (and any of its missing parent topics) as necessary. This should be useful mostly to TopicManager itself. Topic creation: The topic definition will be obtained from the first registered TopicDefnProvider (see addTopicDefnProvider() method) that can provide it. If none is found, then protoListener, if given, will be used to extract the specification for the topic message arguments. So the topic object returned will be either 1. an existing one 2. a new one whose specification was obtained from a TopicDefnProvider 3. a new one whose specification was inferred from protoListener 4. a new one without any specification For the first three cases, the Topic is ready for sending messages. In the last case, topic.isSendable() is false and the specification will be set by the first call to subscribe() (unless you call topicObj.setMsgArgSpec() first to set it yourself). Note that if the topic gets created, missing intervening parents will be created with an empty specification. For instance, if topic A exists, and name="A.B.C", then A.B will also be created. It will only be complete (sendable) if a topic definition provider had its definition. Note also that if protoListener given, and topic already defined, the method does not check whether protoListener adheres to the specification.''' obj = self.getTopic(name, okIfNone=True) if obj: # if object is not sendable but a proto listener was given, # update its specification so that it is sendable if (protoListener is not None) and not obj.isSendable(): allArgsDocs, required = topicArgsFromCallable(protoListener) obj.setMsgArgSpec(allArgsDocs, required) return obj # create missing parents nameTuple = tupleize(name) parentObj = self.__createParentTopics(nameTuple) # now the final topic object, args from listener if provided desc, specGiven = self.__defnProvider.getDefn(nameTuple) # POLICY: protoListener is used only if no definition available if specGiven is None: if protoListener is None: desc = 'UNDOCUMENTED: created without spec' else: allArgsDocs, required = topicArgsFromCallable(protoListener) specGiven = ArgSpecGiven(allArgsDocs, required) desc = 'UNDOCUMENTED: created from protoListener "%s" in module %s' % getID(protoListener) return self.__createTopic(nameTuple, desc, parent = parentObj, specGiven = specGiven) def isTopicSpecified(self, name): '''Returns true if the topic has already been specified, false otherwise. If the return value is true, it is in fact an integer > 0 that says in what way it is specified: - TOPIC_SPEC_ALREADY_DEFINED: as a definition in one of the registered topic definition providers - TOPIC_SPEC_ALREADY_CREATED: as an object in the topic tree, having a complete specification So if caller just wants yes/no, just use return value as boolean as in if topicMgr.isTopicSpecified(name): pass but if reason matters, caller could use (for instance) if topicMgr.isTopicSpecified(name) == topicMgr.TOPIC_SPEC_ALREADY_DEFINED: pass NOTE: if a topic object of given 'name' exists in topic tree, but it does *not* have a complete specification, the return value will be false. ''' alreadyCreated = self.getTopic(name, okIfNone=True) if alreadyCreated is not None and alreadyCreated.isSendable(): return self.TOPIC_SPEC_ALREADY_CREATED # get definition from provider if required, or raise nameTuple = tupleize(name) if self.__defnProvider.isDefined(nameTuple): return self.TOPIC_SPEC_ALREADY_DEFINED return self.TOPIC_SPEC_NOT_SPECIFIED def checkAllTopicsSpecifed(self): '''Check all topics that have been created and raise a ListenerSpecIncomplete exception if one is found that does not have a listener specification. ''' for topic in self._topicsMap.itervalues(): if not topic.isSendable(): raise ListenerSpecIncomplete(topic.getNameTuple()) def delTopic(self, name): '''Undefines the named topic. Returns True if the subtopic was removed, false otherwise (ie the topic doesn't exist). Also unsubscribes any listeners of topic. Note that it must undefine all subtopics to all depths, and unsubscribe their listeners. ''' # find from which parent the topic object should be removed dottedName = stringize(name) try: #obj = weakref( self._topicsMap[dottedName] ) obj = self._topicsMap[dottedName] except KeyError: return False #assert obj().getName() == dottedName assert obj.getName() == dottedName # notification must be before deletion in case self.__treeConfig.notificationMgr.notifyDelTopic(dottedName) #obj()._undefineSelf_(self._topicsMap) obj._undefineSelf_(self._topicsMap) #assert obj() is None return True def getTopics(self, listener): '''Get the list of Topic objects that given listener has subscribed to. Keep in mind that the listener can get messages from sub-topics of those Topics.''' assocTopics = [] for topicObj in self._topicsMap.values(): if topicObj.hasListener(listener): assocTopics.append(topicObj) return assocTopics def __getClosestParent(self, topicNameDotted): '''Returns a pair, (closest parent, tuple path from parent). The first item is the closest parent topic that exists for given topic. The second one is the list of topic names that have to be created to create the given topic. So if topicNameDotted = A.B.C.D, but only A.B exists (A.B.C and A.B.C.D not created yet), then return is (A.B, ['C','D']). Note that if none of the branch exists (not even A), then return will be [root topic, ['A',B','C','D']). Note also that if A.B.C exists, the return will be (A.B.C, ['D']) regardless of whether A.B.C.D exists. ''' subtopicNames = [] headTail = topicNameDotted.rsplit('.', 1) while len(headTail) > 1: parentName = headTail[0] subtopicNames.insert( 0, headTail[1] ) obj = self._topicsMap.get( parentName, None ) if obj is not None: return obj, subtopicNames headTail = parentName.rsplit('.', 1) subtopicNames.insert( 0, headTail[0] ) return self.__allTopics, subtopicNames def __createParentTopics(self, topicName): '''This will find which parents need to be created such that topicName can be created (but doesn't create given topic), and creates them. Returns the parent object.''' assert self.getTopic(topicName, okIfNone=True) is None parentObj, subtopicNames = self.__getClosestParent(stringize(topicName)) # will create subtopics of parentObj one by one from subtopicNames if parentObj is self.__allTopics: nextTopicNameList = [] else: nextTopicNameList = list(parentObj.getNameTuple()) for name in subtopicNames[:-1]: nextTopicNameList.append(name) desc, specGiven = self.__defnProvider.getDefn( tuple(nextTopicNameList) ) if desc is None: desc = 'UNDOCUMENTED: created as parent without specification' parentObj = self.__createTopic( tuple(nextTopicNameList), desc, specGiven = specGiven, parent = parentObj) return parentObj def __createTopic(self, nameTuple, desc, specGiven, parent=None): '''Actual topic creation step. Adds new Topic instance to topic map, and sends notification message (of topic 'pubsub.newTopic') about new topic having been created.''' if specGiven is None: specGiven = ArgSpecGiven() parentAI = None if parent: parentAI = parent._getListenerSpec() argsInfo = ArgsInfo(nameTuple, specGiven, parentAI) if (self.__treeConfig.raiseOnTopicUnspecified and not argsInfo.isComplete()): raise ListenerSpecIncomplete(nameTuple) newTopicObj = Topic(self.__treeConfig, nameTuple, desc, argsInfo, parent = parent) # sanity checks: assert not self._topicsMap.has_key(newTopicObj.getName()) if parent is self.__allTopics: assert len( newTopicObj.getNameTuple() ) == 1 else: assert parent.getNameTuple() == newTopicObj.getNameTuple()[:-1] assert nameTuple == newTopicObj.getNameTuple() # store new object and notify of creation self._topicsMap[ newTopicObj.getName() ] = newTopicObj self.__treeConfig.notificationMgr.notifyNewTopic( newTopicObj, desc, specGiven.reqdArgs, specGiven.argsDocs) return newTopicObj