From 4295a66c70e595d02e14f384432d8eee8dfef013 Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Wed, 2 Jun 2010 14:18:09 -0400
Subject: reconnection quiesce logic

---
 sleekxmpp/xmlstream/xmlstream.py | 36 ++++++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py
index 3bcb3412..e0b3a23c 100644
--- a/sleekxmpp/xmlstream/xmlstream.py
+++ b/sleekxmpp/xmlstream/xmlstream.py
@@ -16,6 +16,7 @@ from . stanzabase import StanzaBase
 from xml.etree import cElementTree
 from xml.parsers import expat
 import logging
+import random
 import socket
 import threading
 import time
@@ -46,6 +47,10 @@ class CloseStream(Exception):
 
 stanza_extensions = {}
 
+RECONNECT_MAX_DELAY = 3600
+RECONNECT_QUIESCE_FACTOR = 1.6180339887498948 # Phi
+RECONNECT_QUIESCE_JITTER = 0.11962656472 # molar Planck constant times c, joule meter/mole
+
 class XMLStream(object):
 	"A connection manager with XML events."
 
@@ -101,7 +106,12 @@ class XMLStream(object):
 
 	def connectTCP(self, host='', port=0, use_ssl=None, use_tls=None, reattempt=True):
 		"Connect and create socket"
-		while reattempt and not self.state['connected']: # the self.state part is redundant.
+
+		# Note that this is thread-safe by merit of being called solely from connect() which
+		# holds the state lock.
+		
+		delay = 1.0 # reconnection delay
+		while self.run:
 			logging.debug('connecting....')
 			try:
 				if host and port:
@@ -115,21 +125,35 @@ class XMLStream(object):
 				else:
 					self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
 				self.socket.settimeout(None) #10)
+
 				if self.use_ssl and self.ssl_support:
 					logging.debug("Socket Wrapped for SSL")
 					self.socket = ssl.wrap_socket(self.socket,ca_certs=self.ca_certs)
-			except:
-				logging.exception("Connection error")
-			try:
+				
 				self.socket.connect(self.address)
 				self.filesocket = self.socket.makefile('rb', 0)
+				
 				if not self.state.transition('connecting','connected'):
 					logging.error( "State transition error!!!!  Shouldn't have happened" )
 				logging.debug('connect complete.')
 				return True
+
 			except socket.error as serr:
-				logging.error("Could not connect. Socket Error #%s: %s" % (serr.errno, serr.strerror))
-				time.sleep(1) # TODO proper quiesce if connection attempt fails
+				logging.exception("Socket Error #%s: %s", serr.errno, serr.strerror)
+				if not reattempt: return False
+			except:
+				logging.exception("Connection error")
+				if not reattempt: return False
+			
+			# quiesce if rconnection fails:
+			# This code based loosely on Twisted internet.protocol
+			# http://twistedmatrix.com/trac/browser/trunk/twisted/internet/protocol.py#L310
+			delay = min(delay * RECONNECT_QUIESCE_JITTER, RECONNECT_MAX_DELAY)
+			delay = random.normalvariate(delay, delay * RECONNECT_QUIESCE_JITTER)
+			logging.debug('Waiting %fs until next reconnect attempt...', delay)
+			time.sleep(delay)
+
+
 	
 	def connectUnix(self, filepath):
 		"Connect to Unix file and create socket"
-- 
cgit v1.2.3


From 1c32668e18c0cbf840694c66a6f724b2d3cb8f29 Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Thu, 3 Jun 2010 07:47:27 -0400
Subject: fixed quiesce algorithm; state transition if connect fails; note
 about use_tls instance variable.

---
 sleekxmpp/xmlstream/xmlstream.py | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py
index e0b3a23c..af95c2bf 100644
--- a/sleekxmpp/xmlstream/xmlstream.py
+++ b/sleekxmpp/xmlstream/xmlstream.py
@@ -101,8 +101,16 @@ class XMLStream(object):
 	
 	def connect(self, host='', port=0, use_ssl=None, use_tls=None):
 		"Link to connectTCP"
-		if self.state.transition('disconnected', 'connecting'):
-			return self.connectTCP(host, port, use_ssl, use_tls)
+		if not self.connectTCP(host, port, use_ssl, use_tls):
+			# return to the 'disconnected' state if connect failed:
+			# otherwise the connect method is not reentrant
+			if not self.state.transition('connecting','disconnected'):
+				logging.error("Couldn't transition to the 'disconnected' state!")
+			return False
+		return True
+
+		# TODO currently a caller can't distinguish between "connection failed" and
+		# "we're already trying to connect from another thread"
 
 	def connectTCP(self, host='', port=0, use_ssl=None, use_tls=None, reattempt=True):
 		"Connect and create socket"
@@ -119,6 +127,7 @@ class XMLStream(object):
 				if use_ssl is not None:
 					self.use_ssl = use_ssl
 				if use_tls is not None:
+					# TODO this variable doesn't seem to be used for anything!
 					self.use_tls = use_tls
 				if sys.version_info < (3, 0):
 					self.socket = filesocket.Socket26(socket.AF_INET, socket.SOCK_STREAM)
@@ -146,9 +155,9 @@ class XMLStream(object):
 				if not reattempt: return False
 			
 			# quiesce if rconnection fails:
-			# This code based loosely on Twisted internet.protocol
+			# This algorithm based loosely on Twisted internet.protocol
 			# http://twistedmatrix.com/trac/browser/trunk/twisted/internet/protocol.py#L310
-			delay = min(delay * RECONNECT_QUIESCE_JITTER, RECONNECT_MAX_DELAY)
+			delay = min(delay * RECONNECT_QUIESCE_FACTOR, RECONNECT_MAX_DELAY)
 			delay = random.normalvariate(delay, delay * RECONNECT_QUIESCE_JITTER)
 			logging.debug('Waiting %fs until next reconnect attempt...', delay)
 			time.sleep(delay)
-- 
cgit v1.2.3


From 2f0f18a8c62db21fa3ba8cc87a6d190aca205c30 Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Thu, 3 Jun 2010 08:07:56 -0400
Subject: added function to retrieve the current state

---
 sleekxmpp/xmlstream/statemachine.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/statemachine.py b/sleekxmpp/xmlstream/statemachine.py
index c5f51765..065d5794 100644
--- a/sleekxmpp/xmlstream/statemachine.py
+++ b/sleekxmpp/xmlstream/statemachine.py
@@ -110,7 +110,14 @@ class StateMachine(object):
 	def reset(self):
 		# TODO need to lock before calling this? 
 		self.transition(self.__current_state, self._default_state)
-	
+
+
+	def current_state(self):
+		'''
+		Return the current state name.
+		'''
+		return self.__current_state
+
 
 	def __getitem__(self, state):
 		'''
-- 
cgit v1.2.3


From da6e1e47dc81f5f9579201644d7c18dd85510368 Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Thu, 3 Jun 2010 08:09:09 -0400
Subject: whups, somehow I lost the 'connecting' lock in connect()

---
 sleekxmpp/xmlstream/xmlstream.py | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py
index af95c2bf..76aecee4 100644
--- a/sleekxmpp/xmlstream/xmlstream.py
+++ b/sleekxmpp/xmlstream/xmlstream.py
@@ -101,6 +101,10 @@ class XMLStream(object):
 	
 	def connect(self, host='', port=0, use_ssl=None, use_tls=None):
 		"Link to connectTCP"
+		if not self.state.transition('disconnected','connecting'):
+			logging.warning("Can't connect now; Already in state %s", self.state.current_state())
+			return False
+
 		if not self.connectTCP(host, port, use_ssl, use_tls):
 			# return to the 'disconnected' state if connect failed:
 			# otherwise the connect method is not reentrant
-- 
cgit v1.2.3


From d20cd6b3e6a7edacfef6010339d7fb7b587a9def Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Thu, 3 Jun 2010 13:51:11 -0400
Subject: added function execution on transition, and more unit tests.

---
 sleekxmpp/xmlstream/xmlstream.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py
index 76aecee4..c407a335 100644
--- a/sleekxmpp/xmlstream/xmlstream.py
+++ b/sleekxmpp/xmlstream/xmlstream.py
@@ -281,7 +281,7 @@ class XMLStream(object):
 			
 			data = None
 			try:
-				data = self.sendqueue.get(True,10)
+				data = self.sendqueue.get(True,5)
 				logging.debug("SEND: %s" % data)
 				self.socket.sendall(data.encode('utf-8'))
 			except queue.Empty:
@@ -372,6 +372,7 @@ class XMLStream(object):
 			try:
 				event = self.eventqueue.get(True, timeout=5)
 			except queue.Empty:
+				logging.debug('Nothing on event queue')
 				event = None
 			if event is not None:
 				etype = event[0]
-- 
cgit v1.2.3


From f54501a3465b84f1be157c1ba99df854dbeaed1d Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Thu, 3 Jun 2010 14:12:06 -0400
Subject: added function execution on transition, and more unit tests.

---
 sleekxmpp/xmlstream/statemachine.py | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/statemachine.py b/sleekxmpp/xmlstream/statemachine.py
index 065d5794..0c841a9f 100644
--- a/sleekxmpp/xmlstream/statemachine.py
+++ b/sleekxmpp/xmlstream/statemachine.py
@@ -10,6 +10,7 @@ import threading
 import time
 import logging
 
+
 class StateMachine(object):
 
 	def __init__(self, states=[]):
@@ -27,7 +28,7 @@ class StateMachine(object):
 				self.__states.append( state )
 	
 	
-	def transition(self, from_state, to_state, wait=0.0):
+	def transition(self, from_state, to_state, wait=0.0, func=None, args=[], kwargs={} ):
 		'''
 		Transition from the given `from_state` to the given `to_state`.  
 		This method will return `True` if the state machine is now in `to_state`.  It
@@ -47,12 +48,22 @@ class StateMachine(object):
 			if thread_should_exit: return
 			# perform actions here after successful transition
 
-		This allows the thread to be interrupted by setting `thread_should_exit=True`
+		This allows the thread to be responsive by setting `thread_should_exit=True`.
+
+		The optional `func` argument allows the user to pass a callable operation which occurs
+		within the context of the state transition (e.g. while the state machine is locked.)
+		If `func` returns a True value, the transition will occur.  If `func` returns a non-
+		True value or if an exception is thrown, the transition will not occur.  Any thrown
+		exception is not caught by the state machine and is the caller's responsibility to handle.
+		If `func` completes normally, this method will return the value returned by `func.`  If
+		values for `args` and `kwargs` are provided, they are expanded and passed like so:  
+		`func( *args, **kwargs )`.
 		'''
 
-		return self.transition_any( (from_state,), to_state, wait=wait )
+		return self.transition_any( (from_state,), to_state, wait=wait, 
+		                            func=func, args=args, kwargs=kwargs )
 	
-	def transition_any(self, from_states, to_state, wait=0.0):
+	def transition_any(self, from_states, to_state, wait=0.0, func=None, args=[], kwargs={} ):
 		'''
 		Transition from any of the given `from_states` to the given `to_state`.
 		'''
@@ -73,10 +84,19 @@ class StateMachine(object):
 				self.lock.wait(wait)
 			
 			if self.__current_state in from_states: # should always be True due to lock
+				
+				return_val = True
+				# Note that func might throw an exception, but that's OK, it aborts the transition
+				if func is not None: return_val = func(*args,**kwargs)
+
+				# some 'false' value returned from func, 
+				# indicating that transition should not occur:
+				if not return_val: return return_val 
+
 				logging.debug(' ==== TRANSITION %s -> %s', self.__current_state, to_state)
 				self.__current_state = to_state
 				self.lock.notifyAll()
-				return True
+				return return_val  # some 'true' value returned by func or True if func was None
 			else:
 				logging.error( "StateMachine bug!!  The lock should ensure this doesn't happen!" )
 				return False
-- 
cgit v1.2.3


From 919c8c5633acd0d638f39c4a7ec8794fc5e94fff Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Thu, 3 Jun 2010 15:21:26 -0400
Subject: tweaked connectTCP call slightly to reduce possibility of
 'connecting' state limbo

---
 sleekxmpp/xmlstream/xmlstream.py | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py
index c407a335..cc5e1ec8 100644
--- a/sleekxmpp/xmlstream/xmlstream.py
+++ b/sleekxmpp/xmlstream/xmlstream.py
@@ -100,18 +100,20 @@ class XMLStream(object):
 		self.filesocket = filesocket
 	
 	def connect(self, host='', port=0, use_ssl=None, use_tls=None):
-		"Link to connectTCP"
+		"Establish a socket connection to the given XMPP server."
 		if not self.state.transition('disconnected','connecting'):
 			logging.warning("Can't connect now; Already in state %s", self.state.current_state())
 			return False
 
-		if not self.connectTCP(host, port, use_ssl, use_tls):
-			# return to the 'disconnected' state if connect failed:
-			# otherwise the connect method is not reentrant
-			if not self.state.transition('connecting','disconnected'):
-				logging.error("Couldn't transition to the 'disconnected' state!")
-			return False
-		return True
+		try:
+			return self.connectTCP(host, port, use_ssl, use_tls)
+		finally:
+			# attempt to ensure once a connection attempt starts, we leave either in the 
+			# 'connected' or 'disconnected' state.  Otherwise the connect method is not reentrant
+			if self.state['connecting']:
+				if not self.state.transition('connecting','disconnected'):
+					logging.error("Couldn't return to the 'disconnected' state after connection failure!")
+
 
 		# TODO currently a caller can't distinguish between "connection failed" and
 		# "we're already trying to connect from another thread"
@@ -285,7 +287,8 @@ class XMLStream(object):
 				logging.debug("SEND: %s" % data)
 				self.socket.sendall(data.encode('utf-8'))
 			except queue.Empty:
-				logging.debug('nothing on send queue')
+#				logging.debug('Nothing on send queue')
+				pass
 			except socket.timeout:
 				# this is to prevent a thread blocked indefinitely
 				logging.debug('timeout sending packet data')
@@ -372,7 +375,7 @@ class XMLStream(object):
 			try:
 				event = self.eventqueue.get(True, timeout=5)
 			except queue.Empty:
-				logging.debug('Nothing on event queue')
+#				logging.debug('Nothing on event queue')
 				event = None
 			if event is not None:
 				etype = event[0]
-- 
cgit v1.2.3


From e7c37c4ec5a31402ba4d3fd95f2ee31d72183a83 Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Fri, 4 Jun 2010 17:00:51 -0400
Subject: connect uses the new function-on-state-transition so when the connect
 method returns you are guaranteed to be either in the 'connected' or
 'disconnected' state.  Could remove the 'connecting' state except  uses it.

---
 sleekxmpp/xmlstream/xmlstream.py | 22 ++++++++--------------
 1 file changed, 8 insertions(+), 14 deletions(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py
index cc5e1ec8..6dbe7b30 100644
--- a/sleekxmpp/xmlstream/xmlstream.py
+++ b/sleekxmpp/xmlstream/xmlstream.py
@@ -101,19 +101,16 @@ class XMLStream(object):
 	
 	def connect(self, host='', port=0, use_ssl=None, use_tls=None):
 		"Establish a socket connection to the given XMPP server."
-		if not self.state.transition('disconnected','connecting'):
-			logging.warning("Can't connect now; Already in state %s", self.state.current_state())
+		
+		if not self.state.transition('disconnected','connected',
+				func=self.connectTCP, args=[host, port, use_ssl, use_tls] ):
+			
+			if self.state['connected']: logging.debug('Already connected')
+			else: logging.warning("Connection failed" )
 			return False
 
-		try:
-			return self.connectTCP(host, port, use_ssl, use_tls)
-		finally:
-			# attempt to ensure once a connection attempt starts, we leave either in the 
-			# 'connected' or 'disconnected' state.  Otherwise the connect method is not reentrant
-			if self.state['connecting']:
-				if not self.state.transition('connecting','disconnected'):
-					logging.error("Couldn't return to the 'disconnected' state after connection failure!")
-
+		logging.debug('Connection complete.')
+		return True
 
 		# TODO currently a caller can't distinguish between "connection failed" and
 		# "we're already trying to connect from another thread"
@@ -148,9 +145,6 @@ class XMLStream(object):
 				self.socket.connect(self.address)
 				self.filesocket = self.socket.makefile('rb', 0)
 				
-				if not self.state.transition('connecting','connected'):
-					logging.error( "State transition error!!!!  Shouldn't have happened" )
-				logging.debug('connect complete.')
 				return True
 
 			except socket.error as serr:
-- 
cgit v1.2.3


From 66cf0c20218657622a5d98aee155df1ea37d9a89 Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Mon, 7 Jun 2010 13:16:02 -0400
Subject: context manager is working but there's a fatal flaw: inside the body
 of the 'with' statement, there's no way to tell whether or not the transition
 occurred or timed out.

---
 sleekxmpp/xmlstream/statemachine.py | 83 +++++++++++++++++++++++++++++--------
 1 file changed, 65 insertions(+), 18 deletions(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/statemachine.py b/sleekxmpp/xmlstream/statemachine.py
index 0c841a9f..51b4aaed 100644
--- a/sleekxmpp/xmlstream/statemachine.py
+++ b/sleekxmpp/xmlstream/statemachine.py
@@ -63,20 +63,22 @@ class StateMachine(object):
 		return self.transition_any( (from_state,), to_state, wait=wait, 
 		                            func=func, args=args, kwargs=kwargs )
 	
+	
 	def transition_any(self, from_states, to_state, wait=0.0, func=None, args=[], kwargs={} ):
 		'''
 		Transition from any of the given `from_states` to the given `to_state`.
 		'''
 
-		with self.lock:
-			for state in from_states:
-				if isinstance(state,tuple) or isinstance(state,list): 
-					raise ValueError( "State %s should be a string.  Did you mean to call 'StateMachine.transition_any()?" % str(state) )
-				if not state in self.__states: 
-					raise ValueError( "StateMachine does not contain from_state %s." % state )
-			if not to_state in self.__states: 
-				raise ValueError( "StateMachine does not contain to_state %s." % to_state )
+		if not (isinstance(from_states,tuple) or isinstance(from_states,list)): 
+				raise ValueError( "from_states should be a list or tuple" )
+
+		for state in from_states:
+			if not state in self.__states: 
+				raise ValueError( "StateMachine does not contain from_state %s." % state )
+		if not to_state in self.__states: 
+			raise ValueError( "StateMachine does not contain to_state %s." % to_state )
 
+		with self.lock:
 			start = time.time()
 			while not self.__current_state in from_states: 
 				# detect timeout:
@@ -102,23 +104,34 @@ class StateMachine(object):
 				return False
 
 
+	def transition_ctx(self, from_state, to_state, wait=0.0):
+		if not from_state in self.__states: 
+			raise ValueError( "StateMachine does not contain from_state %s." % state )
+		if not to_state in self.__states: 
+			raise ValueError( "StateMachine does not contain to_state %s." % to_state )
+
+		return _StateCtx(self, from_state, to_state, wait)
+
+	
 	def ensure(self, state, wait=0.0):
 		'''
 		Ensure the state machine is currently in `state`, or wait until it enters `state`.
 		'''
 		return self.ensure_any( (state,), wait=wait )
 
+
 	def ensure_any(self, states, wait=0.0):
 		'''
 		Ensure we are currently in one of the given `states`
 		'''
-		with self.lock:
-			for state in states:
-				if isinstance(state,tuple) or isinstance(state,list): 
-					raise ValueError( "State %s should be a string.  Did you mean to call 'StateMachine.transition_any()?" % str(state) )
-				if not state in self.__states: 
-					raise ValueError( "StateMachine does not contain state %s." % state )
+		if not (isinstance(states,tuple) or isinstance(states,list)): 
+			raise ValueError('states arg should be a tuple or list')
+
+		for state in states:
+			if not state in self.__states: 
+				raise ValueError( "StateMachine does not contain state '%s'" % state )
 
+		with self.lock:
 			start = time.time()
 			while not self.__current_state in states: 
 				# detect timeout:
@@ -132,6 +145,11 @@ class StateMachine(object):
 		self.transition(self.__current_state, self._default_state)
 
 
+	def _set_state(self, state): #unsynchronized, only call internally after lock is acquired
+		self.__current_state = state
+		return state
+
+
 	def current_state(self):
 		'''
 		Return the current state name.
@@ -146,12 +164,41 @@ class StateMachine(object):
 		'''
 		return self.__current_state == state
 	
+
+class _StateCtx:
+
+	def __init__( self, state_machine, from_state, to_state, wait ):
+		self.state_machine = state_machine
+		self.from_state = from_state
+		self.to_state = to_state
+		self.wait = wait
+		self._timeout = False
+
 	def __enter__(self):
-		self.lock.acquire()
-		return self
+		self.state_machine.lock.acquire()
+		start = time.time()
+		while not self.state_machine[ self.from_state ]: 
+			# detect timeout:
+			if time.time() >= start + self.wait: 
+				logging.debug('StateMachine timeout while waiting for state: %s', self.from_state )
+				self._timeout = True # to indicate we should not transition
+				break
+			self.state_machine.lock.wait(self.wait)
+
+		logging.debug('StateMachine entered context in state: %s', 
+				self.state_machine.current_state() )
+		return self.state_machine
 
 	def __exit__(self, exc_type, exc_val, exc_tb):
-		self.lock.nofityAll()
-		self.lock.release()
+		if exc_val is not None:
+			logging.exception( "StateMachine exception in context, remaining in state: %s\n%s:%s", 
+				self.state_machine.current_state(), exc_type.__name__, exc_val )			
+		elif not self._timeout:
+			logging.debug(' ==== TRANSITION %s -> %s', 
+					self.state_machine.current_state(), self.to_state)
+			self.state_machine._set_state( self.to_state )
+
+		self.state_machine.lock.notifyAll()
+		self.state_machine.lock.release()
 		return False # re-raise any exception
 
-- 
cgit v1.2.3


From 47f1fb16909d3baaec5822b1dcbca89491d0d18c Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Mon, 7 Jun 2010 13:43:37 -0400
Subject: context manager now returns a boolean 'result' as the context
 variable to indicate whether the transition timed out or if you are actually
 locked when entering the context body

---
 sleekxmpp/xmlstream/statemachine.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/statemachine.py b/sleekxmpp/xmlstream/statemachine.py
index 51b4aaed..b1ab7574 100644
--- a/sleekxmpp/xmlstream/statemachine.py
+++ b/sleekxmpp/xmlstream/statemachine.py
@@ -182,12 +182,12 @@ class _StateCtx:
 			if time.time() >= start + self.wait: 
 				logging.debug('StateMachine timeout while waiting for state: %s', self.from_state )
 				self._timeout = True # to indicate we should not transition
-				break
+				return False
 			self.state_machine.lock.wait(self.wait)
 
 		logging.debug('StateMachine entered context in state: %s', 
 				self.state_machine.current_state() )
-		return self.state_machine
+		return True
 
 	def __exit__(self, exc_type, exc_val, exc_tb):
 		if exc_val is not None:
-- 
cgit v1.2.3


From 9464736551311c015f1511e7535c762923838eaf Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Mon, 7 Jun 2010 13:58:15 -0400
Subject: added __str__

---
 sleekxmpp/xmlstream/statemachine.py | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/statemachine.py b/sleekxmpp/xmlstream/statemachine.py
index b1ab7574..704cabdb 100644
--- a/sleekxmpp/xmlstream/statemachine.py
+++ b/sleekxmpp/xmlstream/statemachine.py
@@ -163,6 +163,10 @@ class StateMachine(object):
 		Use `StateMachine.ensure(state)` to wait until the machine enters a certain state.
 		'''
 		return self.__current_state == state
+
+	def __str__(self):
+		return "".join(( "StateMachine(", ','.join(self.__states), "): ", self.__current_state ))
+
 	
 
 class _StateCtx:
-- 
cgit v1.2.3


From 34dc236126d272a16df0915b010dca0e2e38f0d4 Mon Sep 17 00:00:00 2001
From: Thom Nichols <tmnichols@gmail.com>
Date: Mon, 7 Jun 2010 14:41:42 -0400
Subject: added documentation for transition_ctx and removed some superfluous
 comment lines

---
 sleekxmpp/xmlstream/statemachine.py | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

(limited to 'sleekxmpp/xmlstream')

diff --git a/sleekxmpp/xmlstream/statemachine.py b/sleekxmpp/xmlstream/statemachine.py
index 704cabdb..c6e0ea41 100644
--- a/sleekxmpp/xmlstream/statemachine.py
+++ b/sleekxmpp/xmlstream/statemachine.py
@@ -105,6 +105,32 @@ class StateMachine(object):
 
 
 	def transition_ctx(self, from_state, to_state, wait=0.0):
+		'''
+		Use the state machine as a context manager.  The transition occurs on /exit/ from
+		the `with` context, so long as no exception is thrown.  For example:
+		
+		::
+
+			with state_machine.transition_ctx('one','two', wait=5) as locked:
+				if locked:
+					# the state machine is currently locked in state 'one', and will 
+					# transition to 'two' when the 'with' statement ends, so long as 
+					# no exception is thrown.
+					print 'Currently locked in state one: %s' % state_machine['one']
+
+				else:
+					# The 'wait' timed out, and no lock has been acquired
+					print 'Timed out before entering state "one"'
+
+			print 'Since no exception was thrown, we are now in state "two": %s' % state_machine['two']
+
+
+		The other main difference between this method and `transition()` is that the 
+		state machine is locked for the duration of the `with` statement (normally, 
+		after a `transition() occurs, the state machine is immediately unlocked and 
+		available to another thread to call `transition()` again.
+		'''
+
 		if not from_state in self.__states: 
 			raise ValueError( "StateMachine does not contain from_state %s." % state )
 		if not to_state in self.__states: 
-- 
cgit v1.2.3