diff --git a/docs/README.rst b/docs/README.rst index 27b4d40..ff09ab2 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -3,18 +3,15 @@ |gh_actions| |docs| -.. _actor model: https://en.wikipedia.org/wiki/Actor_model -.. _trio: https://github.com/python-trio/trio -.. _multi-processing: https://en.wikipedia.org/wiki/Multiprocessing -.. _trionic: https://trio.readthedocs.io/en/latest/design.html#high-level-design-principles -.. _async sandwich: https://trio.readthedocs.io/en/latest/tutorial.html#async-sandwich -.. _structured concurrent: https://trio.discourse.group/t/concise-definition-of-structured-concurrency/228 +``tractor`` is a `structured concurrent`_, multi-processing_ runtime built on trio_. +Fundamentally ``tractor`` gives you parallelism via ``trio``-"*actors*": +our nurseries_ let you spawn new Python processes which each run a ``trio`` +scheduled runtime - a call to ``trio.run()``. -``tractor`` is a `structured concurrent`_ "`actor model`_" built on trio_ and multi-processing_. - -We pair structured concurrency and true multi-core parallelism with -the aim of being the multi-processing framework *you always wanted*. +We believe the system adhere's to the `3 axioms`_ of an "`actor model`_" +but likely *does not* look like what *you* probably think an "actor +model" looks like, and that's *intentional*. 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`_. @@ -23,12 +20,13 @@ A great place to start is the `trio docs`_ and this `blog post`_. Features -------- - **It's just** a ``trio`` API -- Infinitely nesteable process trees -- Built-in APIs for inter-process streaming -- A (first ever?) "native" multi-core debugger for Python using `pdb++`_ -- Support for multiple process spawning backends -- A modular transport layer, allowing for custom serialization, +- *Infinitely nesteable* process trees +- Built-in inter-process streaming APIs +- A (first ever?) "native" multi-core debugger UX for Python using `pdb++`_ +- Support for a swappable, OS specific, process spawning layer +- A modular transport stack, allowing for custom serialization, communications protocols, and environment specific IPC primitives +- `structured concurrency`_ from the ground up Run a func in a process @@ -244,19 +242,57 @@ distributed Python. You can think of it as a ``trio`` stdlib's ``multiprocessing`` but built on async programming primitives from the ground up. -``tractor``'s nurseries let you spawn ``trio`` *"actors"*: new Python -processes which each run a ``trio`` scheduled runtime - a call to ``trio.run()``. - Don't be scared off by this description. ``tractor`` **is just** ``trio`` but with nurseries for process management and cancel-able streaming IPC. If you understand how to work with ``trio``, ``tractor`` will give you -the parallelism you've been missing. +the parallelism you may have been needing. -"Actors" communicate by exchanging asynchronous messages_ and avoid -sharing state. The intention of this model is to allow for highly -distributed software that, through the adherence to *structured -concurrency*, results in systems which fail in predictable and -recoverable ways. + +Wait, huh?! I thought "actors" have messages, and mailboxes and stuff?! +*********************************************************************** +Let's stop and ask how many canon actor model papers have you actually read ;) + +From our experience many "actor systems" aren't really "actor models" +since they **don't adhere** to the `3 axioms`_ and pay even less +attention to the problem of *unbounded non-determinism* (which was the +whole point for creation of the model in the first place). + +From the author's mouth, **the only thing required** is `adherance to`_ +the `3 axioms`_, *and that's it*. + +``tractor`` adheres to said base requirements of an "actor model":: + + In response to a message, an actor may: + + - send a finite number of new messages + - create a finite number of new actors + - designate a new behavior to process subsequent messages + + +**and** requires *no further api changes* to accomplish this. + +If you want do debate this further please feel free to chime in on our +chat or discuss on one of the following issues *after you've read +everything in them*:: + +- https://github.com/goodboy/tractor/issues/210 +- https://github.com/goodboy/tractor/issues/18 + + +Let's clarify our parlance +************************** +Whether or not ``tractor`` has "actors" underneath should be mostly +irrelevant to users other then for referring to the interactions of our +primary runtime primitives: each Python process + ``trio.run()`` ++ surrounding IPC machinery. These are our high level, base +*runtime-units-of-abstraction* which both *are* (as much as they can +be in Python) and will be referred to as our *"actors"*. + +The main goal of ``tractor`` is is to allow for highly distributed +software that, through the adherence to *structured concurrency*, +results in systems which fail in predictable, recoverable and maybe even +understandable ways; being an "actor model" is just one way to describe +properties of the system. What's on the TODO: @@ -278,6 +314,15 @@ say hi, please feel free to reach us in our `matrix channel`_. If matrix seems too hip, we're also mostly all in the the `trio gitter channel`_! +.. _nurseries: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/#nurseries-a-structured-replacement-for-go-statements +.. _actor model: https://en.wikipedia.org/wiki/Actor_model +.. _trio: https://github.com/python-trio/trio +.. _multi-processing: https://en.wikipedia.org/wiki/Multiprocessing +.. _trionic: https://trio.readthedocs.io/en/latest/design.html#high-level-design-principles +.. _async sandwich: https://trio.readthedocs.io/en/latest/tutorial.html#async-sandwich +.. _structured concurrent: https://trio.discourse.group/t/concise-definition-of-structured-concurrency/228 +.. _3 axioms: https://www.youtube.com/watch?v=7erJ1DV_Tlo&t=162s +.. _adherance to: https://www.youtube.com/watch?v=7erJ1DV_Tlo&t=1821s .. _trio gitter channel: https://gitter.im/python-trio/general .. _matrix channel: https://matrix.to/#/!tractor:matrix.org .. _pdb++: https://github.com/pdbpp/pdbpp @@ -286,7 +331,6 @@ channel`_! .. _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/ .. _trio-parallel: https://github.com/richardsheridan/trio-parallel diff --git a/docs/conf.py b/docs/conf.py index ede4ad4..f0452d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,28 +54,44 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_typlog_theme' +html_theme = 'sphinx_book_theme' -pygments_style = 'sphinx' +pygments_style = 'algol_nu' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - 'logo': 'tractor_logo_side.svg', - 'description': 'Structured concurrent "actors"', - 'github_user': 'goodboy', - 'github_repo': 'tractor', + # 'logo': 'tractor_logo_side.svg', + # 'description': 'Structured concurrent "actors"', + "repository_url": "https://github.com/goodboy/tractor", + "use_repository_button": True, + "home_page_in_toc": False, + "show_toc_level": 1, + "path_to_docs": "docs", + } html_sidebars = { "**": [ - 'logo.html', - 'github.html', - 'relations.html', - 'searchbox.html' - ] + "sbt-sidebar-nav.html", + "sidebar-search-bs.html", + # 'localtoc.html', + ], + # 'logo.html', + # 'github.html', + # 'relations.html', + # 'searchbox.html' + # ] } +# doesn't seem to work? +# extra_navbar = "

nextttt-gennnnn

" + +html_title = '' +html_logo = '_static/tractor_logo_side.svg' +html_favicon = '_static/tractor_logo_side.svg' +# show_navbar_depth = 1 + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/index.rst b/docs/index.rst index 4ed5a47..2bdf993 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,12 +3,13 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -tractor -======= +``tractor`` +=========== + A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: .. _actor model: https://en.wikipedia.org/wiki/Actor_model @@ -58,8 +59,6 @@ say hi, please feel free to ping me on the `trio gitter channel`_! .. _trio gitter channel: https://gitter.im/python-trio/general -.. contents:: - Philosophy ---------- diff --git a/requirements-docs.txt b/requirements-docs.txt index 5c53ba7..2c88be7 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,2 +1,2 @@ sphinx -sphinx_typlog_theme \ No newline at end of file +sphinx_book_theme