diff --git a/docs/index.rst b/docs/index.rst index e0a093f..dbfb56d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,7 +5,7 @@ tractor ======= -An async-native "`actor model`_" built on trio_ and multiprocessing_. +A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_. .. toctree:: :maxdepth: 2 @@ -22,10 +22,12 @@ An async-native "`actor model`_" built on trio_ and multiprocessing_. .. _cancellation: https://trio.readthedocs.io/en/latest/reference-core.html#cancellation-and-timeouts .. _channels: https://en.wikipedia.org/wiki/Channel_(programming) .. _chaos engineering: http://principlesofchaos.org/ +.. _structured concurrent: https://trio.discourse.group/t/concise-definition-of-structured-concurrency/228 ``tractor`` is an attempt to bring trionic_ `structured concurrency`_ to -distributed multi-core Python. +distributed multi-core Python; it aims to be the Python multi-processing +framework *you always wanted*. ``tractor`` lets you spawn ``trio`` *"actors"*: processes which each run a ``trio`` scheduled task tree (also known as an `async sandwich`_). @@ -34,6 +36,53 @@ sharing any state. This model allows for highly distributed software architecture which works just as well on multiple cores as it does over many hosts. +The first step to grok ``tractor`` is to get the basics of ``trio`` down. +A great place to start is the `trio docs`_ and this `blog post`_. + +.. _messages: https://en.wikipedia.org/wiki/Message_passing +.. _trio docs: https://trio.readthedocs.io/en/latest/ +.. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ +.. _structured concurrency: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ +.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts +.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony +.. _async generators: https://www.python.org/dev/peps/pep-0525/ + + +Install +------- +No PyPi release yet! + +:: + + pip install git+git://github.com/goodboy/tractor.git + + +Feel like saying hi? +-------------------- +This project is very much coupled to the ongoing development of +``trio`` (i.e. ``tractor`` gets all its ideas from that brilliant +community). If you want to help, have suggestions or just want to +say hi, please feel free to ping me on the `trio gitter channel`_! + +.. _trio gitter channel: https://gitter.im/python-trio/general + + +.. contents:: + + +Philosophy +---------- +Our tenets non-comprehensively include: + +- strict adherence to the `concept-in-progress`_ of *structured concurrency* +- no spawning of processes *willy-nilly*; causality_ is paramount! +- (remote) errors `always propagate`_ back to the parent supervisor +- verbatim support for ``trio``'s cancellation_ system +- `shared nothing architecture`_ +- no use of *proxy* objects or shared references between processes +- an immersive debugging experience +- anti-fragility through `chaos engineering`_ + ``tractor`` is an actor-model-*like* system in the sense that it adheres to the `3 axioms`_ but does not (yet) fulfil all "unrequirements_" in practise. It is an experiment in applying `structured concurrency`_ @@ -50,37 +99,6 @@ definitely not required). There is first class support for inter-actor streaming using `async generators`_ and ongoing work toward a functional reactive style for IPC. -The first step to grok ``tractor`` is to get the basics of ``trio`` down. -A great place to start is the `trio docs`_ and this `blog post`_. - -.. _messages: https://en.wikipedia.org/wiki/Message_passing -.. _trio docs: https://trio.readthedocs.io/en/latest/ -.. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ -.. _structured concurrency: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ -.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts -.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony -.. _async generators: https://www.python.org/dev/peps/pep-0525/ - - -.. contents:: - - -Philosophy ----------- -``tractor`` aims to be the Python multi-processing framework *you always wanted*. - -Its tenets non-comprehensively include: - -- strict adherence to the `concept-in-progress`_ of *structured concurrency* -- no spawning of processes *willy-nilly*; causality_ is paramount! -- (remote) errors `always propagate`_ back to the parent supervisor -- verbatim support for ``trio``'s cancellation_ system -- `shared nothing architecture`_ -- no use of *proxy* objects or shared references between processes -- an immersive debugging experience -- anti-fragility through `chaos engineering`_ - - .. warning:: ``tractor`` is in alpha-alpha and is expected to change rapidly! Expect nothing to be set in stone. Your ideas about where it should go are greatly appreciated! @@ -88,15 +106,6 @@ Its tenets non-comprehensively include: .. _concept-in-progress: https://trio.discourse.group/t/structured-concurrency-kickoff/55 -Install -------- -No PyPi release yet! - -:: - - pip install git+git://github.com/goodboy/tractor.git - - Examples -------- Note, if you are on Windows please be sure to see the gotchas section @@ -619,13 +628,3 @@ Stuff I'd like to see ``tractor`` do real soon: .. _asyncitertools: https://github.com/vodik/asyncitertools .. _pdb++: https://github.com/antocuni/pdb .. _capability-based security: https://en.wikipedia.org/wiki/Capability-based_security - - -Feel like saying hi? --------------------- -This project is very much coupled to the ongoing development of -``trio`` (i.e. ``tractor`` gets all its ideas from that brilliant -community). If you want to help, have suggestions or just want to -say hi, please feel free to ping me on the `trio gitter channel`_! - -.. _trio gitter channel: https://gitter.im/python-trio/general