[Pydispatcher-cvs] dispatch dispatcher.py,1.2,1.3

[<mcf...@us...>]

Update of /cvsroot/pydispatcher/dispatch
In directory sc8-pr-cvs1:/tmp/cvs-serv17277

Modified Files:
	dispatcher.py 
Log Message:
Added quite a bit of documentation, down to the "connect" function so far.

Index: dispatcher.py
===================================================================
RCS file: /cvsroot/pydispatcher/dispatch/dispatcher.py,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** dispatcher.py	1 Jul 2003 04:25:44 -0000	1.2
--- dispatcher.py	6 Jul 2003 15:00:11 -0000	1.3
***************
*** 1,16 ****
! """Provides global signal dispatching services.
  
! Slightly modified version for vrml and OpenGLContext
! packages.  Modifications:
  
! 	eliminate the cast to string for the signal objects,
! 	which allows for non-string signal values.
  
! 	provide back-reference set for senders/recievers
! 	which dramatically improves performance during system
! 	shutdown or deallocation of nodes
  
! 	refactoring of saferef into seperate module to allow
! 	for general reuse.
  """
  from __future__ import generators
--- 1,31 ----
! """Multiple-producer-multiple-consumer signal-dispatching
  
! dispatcher is the core of the PyDispatcher system,
! providing the primary API and the core logic for the
! system.
  
! Module attributes of note:
  
! 	Any -- Singleton used to signal either "Any Sender" or
! 		"Any Signal".  See documentation of the Any object.
! 	Anonymous -- Singleton used to signal "Anonymous Sender"
! 		See documentation of the Anonymous object.
! 	DispatcherError -- Raised on use of None as a signal
! 		or attempts to disconnect when there is no current
! 		connection.
  
! Internal attributes:
! 	WEAKREF_TYPES -- tuple of types/classes which represent
! 		weak references to receivers, and thus must be de-
! 		referenced on retrieval to retrieve the callable
! 		object
! 	connections -- { senderkey (id) : { signal : [receivers...]}}
! 	senders -- { senderkey (id) : weakref(sender) }
! 		used for cleaning up sender references on sender
! 		deletion
! 	sendersBack -- { receiverkey (id) : [senderkey (id)...] }
! 		used for cleaning up receiver references on receiver
! 		deletion, (considerably speeds up the cleanup process
! 		vs. the original code.)
  """
  from __future__ import generators
***************
*** 38,45 ****
  		return self.__class__.__name__
  
! class Any(_Parameter): pass
  Any = Any()
  
! class Anonymous(_Parameter): pass
  Anonymous = Anonymous()
  
--- 53,84 ----
  		return self.__class__.__name__
  
! class Any(_Parameter):
! 	"""Singleton used to signal either "Any Sender" or "Any Signal"
! 
! 	The Any object can be used with connect, disconnect,
! 	send, or sendExact to signal that the parameter given
! 	Any should react to all senders/signals, not just
! 	a particular sender/signal.
! 	"""
  Any = Any()
  
! class Anonymous(_Parameter):
! 	"""Singleton used to signal "Anonymous Sender"
! 
! 	The Anonymous object is used to signal that the sender
! 	of a message is not specified (as distinct from being
! 	"any sender").  Registering callbacks for Anonymous
! 	will only receive messages sent without senders.  Sending
! 	with anonymous will only send messages to those receivers
! 	registered for Any or Anonymous.
! 
! 	Note:
! 		The default sender for connect is Any, while the
! 		default sender for send is Anonymous.  This has
! 		the effect that if you do not specify any senders
! 		in either function then all messages are routed
! 		as though there was a single sender (Anonymous)
! 		being used everywhere.
! 	"""
  Anonymous = Anonymous()
  
***************
*** 52,66 ****
  
  def connect(receiver, signal=Any, sender=Any, weak=True):
! 	"""Connect receiver to sender for signal.
  	
! 	If sender is Any, receiver will receive signal from any sender.
! 	If signal is Any, receiver will receive any signal from sender.
! 	If sender is None, receiver will receive signal from anonymous.
! 	If signal is Any and sender is None, receiver will receive any 
! 		signal from anonymous.
! 	If signal is Any and sender is Any, receiver will receive any 
! 		signal from any sender.
! 	If weak is true, weak references will be used."""
  	
  	if signal is None:
  		raise DispatcherError, 'signal cannot be None'
--- 91,142 ----
  
  def connect(receiver, signal=Any, sender=Any, weak=True):
! 	"""Connect receiver to sender for signal
! 
! 	receiver -- a callable Python object
! 
! 		if weak is True, then receiver must be weak-referencable
! 		(more precisely saferef.safeRef() must be able to create
! 		a reference to the receiver).
  	
! 		Receivers are fairly flexible in their specification,
! 		as the machinery in the robustApply module takes care
! 		of most of the details regarding figuring out appropriate
! 		subsets of the sent arguments to apply to a given
! 		receiver.
! 
! 		Note:
! 			if receiver is itself a weak reference (a callable),
! 			it will be de-referenced by the system's machinery,
! 			so *generally* weak references are not suitable as
! 			receivers, though some use might be found for the
! 			facility whereby a higher-level library passes in
! 			pre-weakrefed receiver references.
! 
! 	signal -- the signal to which the receiver should respond
! 	
! 		if Any, receiver will receive any signal from the
! 		registered sender.
! 		
! 		Otherwise must be a hashable Python object other than
! 		None (DispatcherError raised on None).
! 		
! 	sender -- the sender to which the receiver should respond
  	
+ 		if Any, receiver will receive registered signals from
+ 		any sender.
+ 		
+ 		if Anonymous, receiver will only receive registered
+ 		signals which do not specify a sender, or specify
+ 		Anonymous explicitly as the sender.
+ 
+ 		Otherwise can be any python object.
+ 		
+ 	weak -- whether to use weak references to the receiver
+ 		By default, the module will attempt to use weak
+ 		references to the receiver objects.  If this parameter
+ 		is false, then strong references will be used.
+ 
+ 	returns None
+ 	"""
  	if signal is None:
  		raise DispatcherError, 'signal cannot be None'
***************
*** 119,123 ****
  
  def getReceivers( sender = Any, signal = Any ):
! 	"""Get list of receivers from global tables"""
  	try:
  		return connections[id(sender)][signal]
--- 195,215 ----
  
  def getReceivers( sender = Any, signal = Any ):
! 	"""Get list of receivers from global tables
! 
! 	This utility function allows you to retrieve the
! 	raw list of receivers from the connections table
! 	for the given sender and signal pair.
! 
! 	Note:
! 		there is no guarantee that this is the actual list
! 		stored in the connections table, so the value
! 		should be treated as a simple iterable/truth value
! 		rather than, for instance a list to which you
! 		might append new records.
! 
! 	Normally you would use liveReceivers( getReceivers( ...))
! 	to retrieve the actual receiver objects as an iterable
! 	object.
! 	"""
  	try:
  		return connections[id(sender)][signal]
***************
*** 126,130 ****
  
  def liveReceivers(receivers):
! 	"""Filter sequence of receivers to get resolved, live receivers"""
  	for receiver in receivers:
  		if isinstance( receiver, WEAKREF_TYPES):
--- 218,228 ----
  
  def liveReceivers(receivers):
! 	"""Filter sequence of receivers to get resolved, live receivers
! 
! 	This is a generator which will iterate over
! 	the passed sequence, checking for weak references
! 	and resolving them, then returning all live
! 	receivers.
! 	"""
  	for receiver in receivers:
  		if isinstance( receiver, WEAKREF_TYPES):