{
    "info": {
        "author": "Erik Allik",
        "author_email": "eallik@gmail.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "Coroutine flow control\n======================\n\nDescription\n-----------\n\nGenerators wrapped with ``@txcoroutine.coroutine`` are otherwise identical to those wrapped with\n``@twisted.internet.defer.inlineCallbacks``, however, the object returned by it is an instance of\n``txcoroutine.Coroutine`` which is a subclass of ``twisted.internet.defer.Deferred``.\n\n``Coroutine`` objects provide an API otherwise identical to that of ``Deferred`` objects, however, calling ``pause``,\n``unpause`` or ``cancel`` on ``Coroutine`` objects transparently applies the same action on all nested ``Deferred``\nobjects that are currently waited on recursively.\n\nSimple example\n--------------\n\nSingle coroutine that calls a ``Deferred``-returning function. The ``Deferred`` is automatically cancelled when the\ncoroutine is stopped.\n\n::\n\n    from __future__ import print_function\n\n    from twisted.internet import reactor\n    from twisted.internet.defer import Deferred\n\n    def get_message():\n        d = Deferred(canceller=lambda _: (\n            print(\"cancelled getting a message\"),\n            heavylifting.cancel(),\n        ))\n        print(\"getting a message...\")\n        heavylifting = reactor.callLater(1.0, d.callback, 'dummy-message')\n        return d\n\n    @coroutine\n    def some_process():\n        try:\n            while True:\n                msg = yield get_message()\n                print(\"processing message: %s\" % (msg,))\n        finally:  # could use `except GeneratorExit` but `finally` is more illustrative\n            print(\"coroutine stopped, cleaning up\")\n\n    def main():\n        proc = some_process()\n        reactor.callLater(3, proc.cancel)  # stop the coroutine 3 seconds later.\n\n    reactor.callWhenRunning(main)\n    reactor.run()\n\n**Output:**\n\n::\n\n    getting a message...\n    processing message: dummy-message\n    getting a message...\n    processing message: dummy-message\n    ...\n    cancelled getting a message\n    coroutine stopped, cleaning up\n\n\nAdvanced example with multiple levels of coroutines and cascaded flow control\n-----------------------------------------------------------------------------\n\n::\n\n    from __future__ import print_function\n\n    from twisted.internet import reactor, task\n    from twisted.internet.defer import Deferred\n\n    @coroutine\n    def level3_process():\n        basetime = reactor.seconds()\n        seconds_passed = lambda: int(round(reactor.seconds() - basetime))\n        try:\n            while True:\n                print(\"iterating: %ss passed\" % seconds_passed())\n                yield sleep(1.0)\n        finally:  # could use `except GeneratorExit` but `finally` is more illustrative\n            print(\"level3_process stopped; cleaning up...\")\n\n    @coroutine\n    def level2_process():\n        try:\n            yield level3_process()\n        finally:\n            print(\"level2_process stopped; cleaning up...\")\n\n    @coroutine\n    def root_process():\n        try:\n            yield level2_process()\n        finally:\n            print(\"root_process stopped; cleaning up...\")\n\n    def main():\n        proc = root_process()\n        reactor.callLater(3, proc.pause)  # pause the coroutine 3 seconds later.\n        reactor.callLater(6, proc.unpause)  # then pause 3 seconds later\n        reactor.callLater(9, proc.cancel)  # then finally stop it 3 seconds later\n\n\n    def sleep(seconds, reactor=reactor):\n        \"\"\"A simple helper for asynchronously sleeping a certain amount of time.\"\"\"\n        return task.deferLater(reactor, seconds, lambda: None)\n\n\n    reactor.callWhenRunning(main)\n    reactor.run()\n\n**Output:**\n\n::\n\n    iterating: 0s passed\n    iterating: 1s passed\n    iterating: 2s passed\n    <<NOTHING PRINTED FOR 4 SECONDS>>\n    iterating: 6s passed\n    iterating: 7s passed\n    iterating: 8s passed\n    level3_process stopped; cleaning up...\n    level2_process stopped; cleaning up...\n    root_process stopped; cleaning up...\n\n\nTail call optimisation\n======================\n\n**Example:**\n\n::\n\n    def fact(n, result=1):\n        if n <= 1:\n            returnValue(result)\n        else:\n            noreturn(fact(n - 1, n * result))\n        yield  # make sure it's a generator\n\n    n = coroutine(fact)(10000).result\n\nNote, ``fact`` itself should not be decorated with ``coroutine``, otherwise the recursive call would simply create\nanother coroutine. This would still support infinite recursion but would be less efficient and consume slightly more\nmemory per each new level introduced because, internally, all the Deferreds would be alive and chained to each other.\n\nThis is mainly meant for recursively and infinitely swapping out behaviour in long running processes. For\nnon-coroutine/non-generator TCO, a simpler approach is also possible by delegating the function invocation directly\nto the trampoline. However, this would be out of the scope of this package.\n\nDescription of operation\n------------------------\n\nThe memory held by the caller is immediately released as it swaps itself out for another process, while the ``Deferred``\nthat was originally returned is still bound to the ongoing processing.\n\n::\n\n    @coroutine\n    def process():\n        big_obj = SomeBigObject()\n        noreturn(process_state1())  # big_obj is released immediately\n        yield\n\n    def process_state1():\n        another_big_obj = SomeBigObject()\n        noreturn(process_state2())  # another_big_obj is released immediately\n        yield\n\n    def process_state2():\n        yield do_something()\n        returnValue(123)\n\n    def some_other_coroutine():\n        yield process()  # will block until state2 has returned 123\n\nThis cannot be achieved with plain ``@inlineCallbacks`` while satisfying both requirements.\n\nMemory-efficient solution with ``@inlineCallbacks``:\n\n::\n\n    @inlineCallbacks\n    def process():\n         big_obj = SomeBigObject()\n         process_state1()  # big_obj is released immediately but the `Deferred` returned by process is fired immediately\n         yield\n\nSolution with ``@inlineCallbacks`` keeping ``Deferred`` consistency but not releasing memory:\n\n::\n\n    @inlineCallbacks\n    def process():\n         big_obj = SomeBigObject()\n         yield process_state1()  # big_obj is not released until process_state1 completes\n\n\nMiscellaneous\n-------------\n\nSee also http://racecondev.wordpress.com/2012/08/17/a-coroutine-decorator-for-twisted/\nThe blog post doesn't mention tail-call optimisation though.",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://github.com/eallik/txcoroutine/",
        "keywords": null,
        "license": "BSD",
        "maintainer": null,
        "maintainer_email": null,
        "name": "txcoroutine",
        "package_url": "https://pypi.org/project/txcoroutine/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/txcoroutine/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "http://github.com/eallik/txcoroutine/"
        },
        "release_url": "https://pypi.org/project/txcoroutine/1.0.9/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Coroutines for Twisted with tail call optimization support",
        "version": "1.0.9"
    },
    "last_serial": 801119,
    "releases": {
        "1.0.7": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "661811034ea6ad60e5bf98627400b722",
                    "sha256": "c08e231e37002e152245a581d67889f866864766312f0912879b2aec756daffc"
                },
                "downloads": -1,
                "filename": "txcoroutine-1.0.7.tar.gz",
                "has_sig": false,
                "md5_digest": "661811034ea6ad60e5bf98627400b722",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 6140,
                "upload_time": "2012-08-18T11:05:56",
                "url": "https://files.pythonhosted.org/packages/57/b9/dcf4b96accf0fbf3c1be7bd0f64f7d27547c4603a0eff01428f4c3caad07/txcoroutine-1.0.7.tar.gz"
            }
        ],
        "1.0.8": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8a6ec0f445227771091e83cafc5f3859",
                    "sha256": "548bdb228b10a7d007c35eed84e1a30659ce861e06ce457cc309dff428ab8a3b"
                },
                "downloads": -1,
                "filename": "txcoroutine-1.0.8.tar.gz",
                "has_sig": false,
                "md5_digest": "8a6ec0f445227771091e83cafc5f3859",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 6162,
                "upload_time": "2012-08-27T13:01:29",
                "url": "https://files.pythonhosted.org/packages/d5/d3/513f26ab839409d1e503491fa02e410868d72d487958c59d12909e1b0298/txcoroutine-1.0.8.tar.gz"
            }
        ],
        "1.0.9": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8caa92910b5dc19001956c838ebc52e9",
                    "sha256": "70e5091933fc2d46c44d94bb7b7bb06cf74c4e194ec4d452e283b442a5cfa697"
                },
                "downloads": -1,
                "filename": "txcoroutine-1.0.9.tar.gz",
                "has_sig": false,
                "md5_digest": "8caa92910b5dc19001956c838ebc52e9",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 7016,
                "upload_time": "2012-10-15T14:41:14",
                "url": "https://files.pythonhosted.org/packages/09/7c/c98c03a4b96f3324551366abc99376e64d3aa2865aa92babd5f99153619d/txcoroutine-1.0.9.tar.gz"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "2dc79e647073f74e8f047e63447a820b",
                    "sha256": "eba454759bbaf05a3d01c4a935292879fde8a1013f3c82a6aceb29894dea0aeb"
                },
                "downloads": -1,
                "filename": "txcoroutine-1.0.9.win32.exe",
                "has_sig": false,
                "md5_digest": "2dc79e647073f74e8f047e63447a820b",
                "packagetype": "bdist_wininst",
                "python_version": "any",
                "requires_python": null,
                "size": 74818,
                "upload_time": "2012-10-15T14:41:16",
                "url": "https://files.pythonhosted.org/packages/c4/d8/6712233cc5b3a296a5642e064f6800c87bb9b69cfdf0c2122ac4fac9567a/txcoroutine-1.0.9.win32.exe"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "8caa92910b5dc19001956c838ebc52e9",
                "sha256": "70e5091933fc2d46c44d94bb7b7bb06cf74c4e194ec4d452e283b442a5cfa697"
            },
            "downloads": -1,
            "filename": "txcoroutine-1.0.9.tar.gz",
            "has_sig": false,
            "md5_digest": "8caa92910b5dc19001956c838ebc52e9",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 7016,
            "upload_time": "2012-10-15T14:41:14",
            "url": "https://files.pythonhosted.org/packages/09/7c/c98c03a4b96f3324551366abc99376e64d3aa2865aa92babd5f99153619d/txcoroutine-1.0.9.tar.gz"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "2dc79e647073f74e8f047e63447a820b",
                "sha256": "eba454759bbaf05a3d01c4a935292879fde8a1013f3c82a6aceb29894dea0aeb"
            },
            "downloads": -1,
            "filename": "txcoroutine-1.0.9.win32.exe",
            "has_sig": false,
            "md5_digest": "2dc79e647073f74e8f047e63447a820b",
            "packagetype": "bdist_wininst",
            "python_version": "any",
            "requires_python": null,
            "size": 74818,
            "upload_time": "2012-10-15T14:41:16",
            "url": "https://files.pythonhosted.org/packages/c4/d8/6712233cc5b3a296a5642e064f6800c87bb9b69cfdf0c2122ac4fac9567a/txcoroutine-1.0.9.win32.exe"
        }
    ]
}