Some more documentation and cleanup of the procpool contrib.

contrib/procpools/README.txt

@@ -0,0 +1,40 @@
+
+ProcPools
+---------
+
+This contrib defines a process pool subsystem for Evennia.
+
+A process pool handles a range of separately running processes that
+can accept information from the main Evennia process. The pool dynamically
+grows and shrinks depending on the need (and will queue requests if there
+are no free slots available).
+
+The main use of this is to launch long-running, possibly blocking code
+in a way that will not freeze up the rest of the server. So you could 
+execute time.sleep(10) on the process pool without anyone else on the 
+server noticing anything. 
+
+This folder has the following contents: 
+
+ampoule/ - this is a separate library managing the process pool. You 
+           should not need to touch this.
+
+Python Procpool
+---------------
+python_procpool.py - this implements a way to execute arbitrary python
+           code on the procpool. Import run_async() from this
+           module in order to use this functionality in-code
+           (this is a replacement to the in-process run_async
+           found in src.utils.utils).
+python_procpool_plugin.py - this is a plugin module for the python
+           procpool, to start and add it to the server. Adding it 
+           is a single line in your settings file - see the header
+           of the file for more info. 
+
+
+
+Adding other Procpools
+----------------------
+To add other types of procpools (such as for executing other remote languages
+           than Python), you can pretty much mimic the layout of python_procpool.py
+           and python_procpool_plugin.py.

contrib/procpools/python_procpool.py

@@ -1,16 +1,30 @@
 """
-ProcPool
+Python ProcPool
 
-This module implements and handles processes running under the AMPoule
-pool. The ProcPool can accept data from processes and runs them in a
-dynamically changing pool of processes, talking to them over AMP. This
-offers full asynchronous operation (Python threading does not work as
-well for this).
+Evennia Contribution - Griatch 2012
 
-The ExecuteCode command found here is used by src.utils.utils.run_async()
-to launch snippets of code on the process pool. The pool itself is a
-service named "Process Pool" and is controlled from src/server/server.py.
-It can be customized via settings.PROCPOOL_*
+The ProcPool is used to execute code on a separate process. This allows for
+true asynchronous operation. Process communication happens over AMP and is
+thus fully asynchronous as far as Evennia is concerned.
+
+The process pool is implemented using a slightly modified version of
+the Ampoule package (included).
+
+The python_process pool is a service activated with the instructions
+in python_procpool_plugin.py.
+
+To use, import run_async from this module and use instead of the
+in-process version found in src.utils.utils. Note that this is a much
+more complex function than the default run_async, so make sure to read
+the header carefully.
+
+To test it works, make sure to activate the process pool, then try the
+following as superuser:
+
+@py from contrib.procpools.python_procpool import run_async;run_async("_return('Wohoo!')", at_return=self.msg, at_err=self.msg)
+
+You can also try to import time and do time.sleep(5) before the
+_return statement, to test it really is asynchronous.
 
 """
 

contrib/procpools/python_procpool_plugin.py

@@ -1,14 +1,21 @@
 """
-This is a plugin for the Evennia services.
+Python ProcPool plugin
 
-To add, simply add the path to this module
-("contrib.procpools.python_procpool_plugin") to the
-settings.SERVER_SERVICES_PLUGIN_MODULES list and reboot the server.
+Evennia contribution - Griatch 2012
+
+This is a plugin for the Evennia services. It will make the service
+and run_async in python_procpool.py available to the system.
+
+To activate, add the following line to your settings file:
+
+SERVER_SERVICES_PLUGIN_MODULES.append("contrib.procpools.python_procpool_plugin")
+
+Next reboot the server and the new service will be available.
 
 If you want to adjust the defaults, copy this file to
-game/gamesrc/conf/, re-point settings.SERVER_SERVICES_PLUGINS_MODULES
-and edit the file there. This is to avoid eventual upstream
-modifications to this file.
+game/gamesrc/conf/ and re-point
+settings.SERVER_SERVICES_PLUGINS_MODULES to that file instead.  This
+is to avoid clashes with eventual upstream modifications to this file.
 
 It is not recommended to use this with an SQLite3 database, at least
 if you plan to do many out-of-process database write - SQLite3 does