Commits

Jan-Philip Gehrcke committed c6a1bc3

Make README and CHANGELOG have rst file extensions.

  • Participants
  • Parent commits 3ca5519

Comments (0)

Files changed (5)

File CHANGELOG

-Version 0.3.0 (TBD)
-----------------------------
-    - Add bidirectional message transfer channels for IPC.
-    - Prevent multiprocessing from swallowing SIGCHLD signals. Eliminates race
-      condition between poll via os.waitpid() and libev child watchers.
-    - Don't pass dispensable gipc handles to child.
-    - Properly deal with handles that are locked for I/O operation while being
-      inherited by child.
-    - Various minor code changes, and a new class of unit tests for more complex
-      scenarios.
-    
-
-Version 0.2.0 (Jan 31, 2013)
-----------------------------
-    - Remove gevent hub threadpool before destroying hub in child (makes gevent
-      reset in child work more reliable).
-
-
-Version 0.1.0 (Dec 12, 2012)
-----------------------------
-    - Initial release.

File CHANGELOG.rst

+Version 0.3.0 (TBD)
+----------------------------
+    - Add bidirectional message transfer channels for IPC.
+    - Prevent multiprocessing from swallowing SIGCHLD signals. Eliminates race
+      condition between poll via os.waitpid() and libev child watchers.
+    - Don't pass dispensable gipc handles to child.
+    - Properly deal with handles that are locked for I/O operation while being
+      inherited by child.
+    - Various minor code changes, and a new class of unit tests for more complex
+      scenarios.
+    
+
+Version 0.2.0 (Jan 31, 2013)
+----------------------------
+    - Remove gevent hub threadpool before destroying hub in child (makes gevent
+      reset in child work more reliable).
+
+
+Version 0.1.0 (Dec 12, 2012)
+----------------------------
+    - Initial release.

File README

-
-What is gipc?
-=============
-Naive usage of Python's multiprocessing package in the context of a
-gevent-powered application may raise various problems and most likely breaks the
-application in many ways.
-
-gipc (pronunciation "gipsy") is developed with the motivation to solve these
-issues transparently. With gipc, multiprocessing.Process-based child processes
-can safely be created anywhere within your gevent-powered application. The API
-of multiprocessing.Process objects is provided in a gevent-cooperative fashion.
-Furthermore, gipc comes up with a pipe-based transport layer for
-gevent-cooperative inter-process communication and useful helper constructs.
-gipc is lightweight and simple to integrate.
-
-
-What are the boundary conditions?
-=================================
-Currently, gipc is tested on CPython 2.6 & 2.7 and developed against gevent
-1.0rc2.
-
-
-Where is the documentation?
-===========================
-The API documentation and further details can be found at
-http://gehrcke.de/gipc.
-
-
-Is gipc stable?
-===============
-Development began in late 2012, so it is far from being mature. However, as of
-version 0.3.0, I am not aware of any fundamental issue. gipc's basic approach
-has proven to be reasonable. gipc is developed with a strong focus on
-reliability and with best intentions in mind. Via extensive unit testing, it has
-been validated to work reliably in scenarios of low and medium complexity. It is
-ready to be evaluated in the context of serious projects. Please let me know how
-gipc performs for you.
-
-
-Where should I download gipc?
-=============================
-Releases are available at `PyPI <http://pypi.python.org/pypi/gipc>`_.
-The development version can be retrieved from the mercurial repository at
-`bitbucket <https://bitbucket.org/jgehrcke/gipc>`_.
-
-
-How can the unit tests be run?
-==============================
-If you run into troubles with gipc, it is a good idea to run the unit test suite
-under your conditions. gipc's unit tests are written for
-`pytest <http://pytest.org>`_. With ``gipc/test`` (included in the release)
-being the current working directory, I usually run tests like this::
-
-    $ py.test -v
-
-
-How is code audit perfomed?
-===========================
-I use `pep8 <http://pypi.python.org/pypi/pep8>`_ and
-`pylint <http://pypi.python.org/pypi/pylint>`_. Have a look at ``audit.sh`` in
-the code repository. Unit test code coverage analysis requires
-`coverage <http://pypi.python.org/pypi/coverage>`_ and
-`pytest-cov <http://pypi.python.org/pypi/pytest-cov>`_. ``audit.sh`` leaves
-behind a coverage HTML report in the ``coverage_html`` directory.
-
-
-Contact & Help
-==============
-Your feedback and questions are highly appreciated. For now, please contact me
-via mail at jgehrcke@googlemail.com or use the
-`Bitbucket issue tracker <https://bitbucket.org/jgehrcke/gipc/issues>`_.
-
-
-Author & license
-================
-``gipc`` is written and maintained by `Jan-Philip Gehrcke <http://gehrcke.de>`_.
-It is licensed under the
-`Apache License 2.0 <http://www.apache.org/licenses/LICENSE-2.0.txt>`_.
+
+What is gipc?
+=============
+Naive usage of Python's multiprocessing package in the context of a
+gevent-powered application may raise various problems and most likely breaks the
+application in many ways.
+
+gipc (pronunciation "gipsy") is developed with the motivation to solve these
+issues transparently. With gipc, multiprocessing.Process-based child processes
+can safely be created anywhere within your gevent-powered application. The API
+of multiprocessing.Process objects is provided in a gevent-cooperative fashion.
+Furthermore, gipc comes up with a pipe-based transport layer for
+gevent-cooperative inter-process communication and useful helper constructs.
+gipc is lightweight and simple to integrate.
+
+
+What are the boundary conditions?
+=================================
+Currently, gipc is developed against gevent 1.0rc2. It is tested on CPython 2.6
+& 2.7 on Linux as well as on Windows.
+
+
+Where are documentation and changelog?
+======================================
+The API documentation and further details can be found at
+http://gehrcke.de/gipc. The changelog can be retrieved from Bitbucket:
+https://bitbucket.org/jgehrcke/gipc/src/tip/CHANGELOG.rst
+
+
+Is gipc stable?
+===============
+Development began in late 2012, so it is far from being mature. However, as of
+version 0.3.0, I am not aware of any fundamental issue. gipc's basic approach
+has proven to be reasonable. gipc is developed with a strong focus on
+reliability and with best intentions in mind. Via extensive unit testing, it has
+been validated to work reliably in scenarios of low and medium complexity. It is
+ready to be evaluated in the context of serious projects. Please let me know how
+gipc performs for you.
+
+
+Where should I download gipc?
+=============================
+Releases are available at `PyPI <http://pypi.python.org/pypi/gipc>`_.
+The development version can be retrieved from the mercurial repository at
+`bitbucket <https://bitbucket.org/jgehrcke/gipc>`_.
+
+
+How can the unit tests be run?
+==============================
+If you run into troubles with gipc, it is a good idea to run the unit test suite
+under your conditions. gipc's unit tests are written for
+`pytest <http://pytest.org>`_. With ``gipc/test`` (included in the release)
+being the current working directory, I usually run tests like this::
+
+    $ py.test -v
+
+
+How is code audit perfomed?
+===========================
+I use `pep8 <http://pypi.python.org/pypi/pep8>`_ and
+`pylint <http://pypi.python.org/pypi/pylint>`_. Have a look at ``audit.sh`` in
+the code repository. Unit test code coverage analysis requires
+`coverage <http://pypi.python.org/pypi/coverage>`_ and
+`pytest-cov <http://pypi.python.org/pypi/pytest-cov>`_. ``audit.sh`` leaves
+behind a coverage HTML report in the ``coverage_html`` directory.
+
+
+Contact & help
+==============
+Your feedback and questions are highly appreciated. For now, please contact me
+via mail at jgehrcke@googlemail.com or use the
+`Bitbucket issue tracker <https://bitbucket.org/jgehrcke/gipc/issues>`_.
+
+
+Author & license
+================
+``gipc`` is written and maintained by `Jan-Philip Gehrcke <http://gehrcke.de>`_.
+It is licensed under the
+`Apache License 2.0 <http://www.apache.org/licenses/LICENSE-2.0.txt>`_.

File docs/index.rst

 .. _what:
 
 gipc (pronunciation “gipsy”) is a Python package tested on CPython 2.6 and
-2.7.
+2.7 on Linux as well as on Windows.
 
 What is gipc good for?
 ======================
 application may raise various problems and most likely breaks the application in
 many ways. gipc is developed with the motivation to solve these issues
 transparently and make using gevent in combination with multiprocessing-based
-child processes and inter-process communication (IPC) a no-brainer again.
+child processes and inter-process communication (IPC) a no-brainer again:
 
-**With gipc, multiprocessing.Process-based child
-processes can safely be created and monitored anywhere within your
-gevent-powered application. Malicious side-effects of child process creation
-in the context of gevent are prevented. The API of multiprocessing.Process
-objects is provided in a gevent-cooperative fashion. Furthermore, gipc comes
-up with a pipe-based transport layer for gevent-cooperative IPC.**
+- **With gipc, multiprocessing.Process-based child
+  processes can safely be created and monitored anywhere within your
+  gevent-powered application. Malicious side-effects of child process creation
+  in the context of gevent are prevented.**
+- **The API of multiprocessing.Process objects is provided in a
+  gevent-cooperative fashion.**
+- **gevent natively works in children.**
+- **gipc comes up with a pipe-based transport layer for gevent-cooperative
+  IPC.**
+- **gipc is lightweight and simple to integrate.**
 
-gipc is lightweight and simple to integrate. In the following code snippet,
-a Python object is sent from a greenlet in the main process through a pipe to a
-child process::
+In the following code snippet, a Python object is sent from a greenlet in the
+main process through a pipe to a child process::
 
     import gevent
     import gipc
 ----------------------------------------------------
 
 Depending on the operating system, child process creation via Python's
-multiprocessing in the context of gevent requires special care. Most care is
-required on POSIX-compliant systems. There, a fork might yield a faulty libev
-event loop state in the child. Most noticable, greenlets spawned before forking
-are cloned and haunt in the child upon context switch. Consider this code
-running on Unix (tested with Python 2.7 & gevent 1.0rc2)::
+multiprocessing in the context of gevent requires special treatment. Most care
+is needed on POSIX-compliant systems. There, a fork might yield a faulty libev
+event loop state in the child. Most noticeable, greenlets spawned before
+forking are cloned and haunt in the child upon context switch. Consider this
+code running on Unix (tested with Python 2.7 & gevent 1.0rc2)::
 
     import gevent
     import multiprocessing
 the pipe. It is retrieved at the ``c2`` end of the pipe in the child. The other
 message is sent from the spooky writelet clone in the child. It is also written
 to the ``c1`` end of the pipe which has implicitly been duplicated during
-forking. Duplicated greenlets in the child of course only run when a context
-switch is triggered; in this case via ``gevent.sleep(0)``. As you can imagine,
-this behavior in general might lead to a wide range of side-effects and tedius
+forking. Greenlet clones in the child of course only run when a context switch
+is triggered; in this case via ``gevent.sleep(0)``. As you can imagine, this
+behavior in general might lead to a wide range of side-effects and tedious
 debugging sessions.
 
 In addition, the code above contains several non-cooperatively blocking method
 calls: ``readchild.join()`` as well as the ``send()``/``recv()`` calls (of
-``multiprocessing.Connection`` objects) block the calling thread and do not
-allow for context switches.
+``multiprocessing.Connection`` objects in general) block the calling thread and
+do not allow for context switches.
 
 gipc overcomes these and other challenges for you transparently and in a
 straight-forward fashion. It provides high performing gevent-cooperative