
Beyond the Basics
===================


Topic Definition Tree and Providers
-------------------------------------

topic definition tree and its syntax, topic tree printing


Listener lifetime 
------------------

Listeners are subscribed in pubsub via weak reference only. 
What this means concretely is that a listener is automatically
unsubscribed as soon as there is no application code that 
refers to it, ie as soon as it is garbage collected. This is 
particularly useful when listeners are methods of objects that can 
be destroyed during the lifetime of an application (this is 
not the only case): you do not need to add code to track when 
the listener is no longer in use, pubsub does it for you. 

A consequence of this is that you cannot subscribe temporaries, 
as would be created when wrapping a listener (for, say, currying). 
For instance, :: 

	class wrapper: 
		def __init__(self, fn): 
			...
	def listener(): pass
	pub.subscribe(wrapper(listener), "topic")
	
This will not subscribe anything: the wrapper instance is a 
temporary, so when pub.subscribe() returns, the temporary is 
garbage collected and unsubscribed! The correct way of doing 
this would be ::

	wrappedListener = wrapper(listener)
	pub.subscribe(wrappedListener, "topic")


Pubsub notifications
---------------------

It can be useful, at least during application development, to 
have some code called when pubsub takes certain types of actions. 
Pubsub supports "notification handlers" and notification flags: 

* a *notification handler* is an instance of a class that defines 
  several methods to handle one, more or all of the types of 
  notifications supported by pubsub
* a *notification flag* is a boolean used to toggle a particular
  type of notification on or off; there are several types of 
  notifications::
  
	subscribe
	sendMessage
	newTopic
	delTopic
	listenerDead
	
The notification flags are changed via pub.setNotifications():
  
A notification handler must adhere to the INotificationHandler
protocol defined in pubsub.utils modules::

	import pubsub.utils
	class MyNotifHandler(INotificationHandler):
		def onSendMessage(...):
	
	pub.addNotificationHandler( MyNotifHandler() )
	
A notification handler is held by strong reference.


Listener exceptions
--------------------

A sender has no way of knowing which listeners are subscribed to 
the topic of the message it is about to send. As a result, it 
cannot make any assumptions about the exception handling of the 
listeners: it must assume that listeners let no exception escape
their scope. If an exception does escape a listener, it interrupts
the sendMessage() call. 

Pubsub supports defining a "listener exception" handler: an 
object that adhere to the IListenerExcHandler protocol to gracefully
handle the exception. This typically consists of printing an 
exception message to the appropriate part of your application GUI. 



Automatic parameters
----------------------

The dafault values of listeners are examined at subscription
time to determine if there are special values that the listener 
should get. One such special value is the topic object corresponding
to the full topic message::

	def listener(topic=pub.AUTO_TOPIC_OBJ): 
		print "real topic is", topic.getName()
	pub.subscribe(listener, "some_topic")
	pub.sendMessage("some_topic") # no data 
		
Here the MDS of "some_topic" is empty: pubsub infers from the
listener signature that it should add the pub.TopicObj object
to the listener call when a "some_topic" message is sent, and 
does not include it in the MDS of "some_topic" (so that each 
listener can decide whether it needs such object). 




Miscellaneous
--------------

other types of errors
other: topic creation, listener validation, Listener, TopicObj

Other
=======

arg1 messaging protocol
migrating from old pubsub
multithreaded apps
pubsub in wxPython (old vs new pubsub, autopubsubsetupv1/setupv1; wxPy v2.8.11)
multiple publisher domains