From 6f4b9efa25785f4e31af08b728883d2d703f76ef Mon Sep 17 00:00:00 2001
From: Patrick Jentsch <p.jentsch@uni-bielefeld.de>
Date: Mon, 2 Sep 2019 09:17:00 +0200
Subject: [PATCH] Add some comments and remove debug code.

---
 app/main/events.py | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/app/main/events.py b/app/main/events.py
index 106f133d..b0f2ce04 100644
--- a/app/main/events.py
+++ b/app/main/events.py
@@ -16,9 +16,12 @@ disconnected = []
 @socketio.on('connect')
 @login_required
 def connect():
-    # print('{} connected'.format(current_user.username))
-    # send('You entered the room {}'.format(request.sid),
-    #      room=request.sid)
+    '''
+    ' The Socket.IO module creates a session id (sid) on each request. The
+    ' initiating client is automatically placed in a room with that sid, which
+    ' will be used for further information exchange generated by a background
+    ' task associated with the sid.
+    '''
     socketio.start_background_task(background_task,
                                    current_user.id,
                                    request.sid)
@@ -27,8 +30,11 @@ def connect():
 @socketio.on('disconnect')
 @login_required
 def disconnect():
+    '''
+    ' On disconnect the session id (sid) of the connection gets placed in the
+    ' disconnected list (see above).
+    '''
     disconnected.append(request.sid)
-    #print('{} disconnected'.format(current_user.username))
 
 
 def background_task(user_id, session_id):
@@ -39,13 +45,19 @@ def background_task(user_id, session_id):
     '
     ' NOTE: The initial values are send as a init-* events.
     '       The JSON patches are send as update-* events.
+    '
+    '       > where '*' is either 'corpora' or 'jobs'
+    '''
+    '''
+    ' Create an app instance to get access to an app_context with which db
+    ' operations are fulfilled.
     '''
     app = create_app(os.getenv('FLASK_CONFIG') or 'default', main=False)
 
     with app.app_context():
         user = db.session.query(User).filter_by(id=user_id).first()
         ''' Get current values from the database. '''
-        corpora =  user.corpora_as_dict()
+        corpora = user.corpora_as_dict()
         jobs = user.jobs_as_dict()
         ''' Send initial values. '''
         socketio.emit('init-corpora',
@@ -56,8 +68,6 @@ def background_task(user_id, session_id):
                       room=session_id)
         ''' TODO: Implement maximum runtime for this loop. '''
         while session_id not in disconnected:
-            # print(session_id + ' running')
-            # socketio.emit('message', 'heartbeat', room=session_id)
             ''' Get current values from the database '''
             new_corpora = user.corpora_as_dict()
             new_jobs = user.jobs_as_dict()
@@ -73,9 +83,8 @@ def background_task(user_id, session_id):
                 socketio.emit('update-jobs',
                               jobs_patch.to_string(),
                               room=session_id)
-            ''' Set new values as a reference for the next iteration. '''
+            ''' Set new values as references for the next iteration. '''
             corpora = new_corpora
             jobs = new_jobs
             socketio.sleep(3)
     disconnected.remove(session_id)
-    # print(session_id + ' stopped')