forked from goodboy/tractor
1
0
Fork 0

Merge pull request #211 from goodboy/new_docs_polish

New docs theme, readme actors rant.
docs_revamp
goodboy 2021-06-14 07:33:02 -04:00 committed by GitHub
commit e98302212a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 101 additions and 42 deletions

View File

@ -3,18 +3,15 @@
|gh_actions| |gh_actions|
|docs| |docs|
.. _actor model: https://en.wikipedia.org/wiki/Actor_model ``tractor`` is a `structured concurrent`_, multi-processing_ runtime built on trio_.
.. _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
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 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
We pair structured concurrency and true multi-core parallelism with model" looks like, and that's *intentional*.
the aim of being the multi-processing framework *you always wanted*.
The first step to grok ``tractor`` is to get the basics of ``trio`` down. 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`_. 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 Features
-------- --------
- **It's just** a ``trio`` API - **It's just** a ``trio`` API
- Infinitely nesteable process trees - *Infinitely nesteable* process trees
- Built-in APIs for inter-process streaming - Built-in inter-process streaming APIs
- A (first ever?) "native" multi-core debugger for Python using `pdb++`_ - A (first ever?) "native" multi-core debugger UX for Python using `pdb++`_
- Support for multiple process spawning backends - Support for a swappable, OS specific, process spawning layer
- A modular transport layer, allowing for custom serialization, - A modular transport stack, allowing for custom serialization,
communications protocols, and environment specific IPC primitives communications protocols, and environment specific IPC primitives
- `structured concurrency`_ from the ground up
Run a func in a process 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 stdlib's ``multiprocessing`` but built on async programming primitives
from the ground up. 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`` Don't be scared off by this description. ``tractor`` **is just** ``trio``
but with nurseries for process management and cancel-able streaming IPC. but with nurseries for process management and cancel-able streaming IPC.
If you understand how to work with ``trio``, ``tractor`` will give you 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 Wait, huh?! I thought "actors" have messages, and mailboxes and stuff?!
distributed software that, through the adherence to *structured ***********************************************************************
concurrency*, results in systems which fail in predictable and Let's stop and ask how many canon actor model papers have you actually read ;)
recoverable ways.
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: 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 matrix seems too hip, we're also mostly all in the the `trio gitter
channel`_! 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 .. _trio gitter channel: https://gitter.im/python-trio/general
.. _matrix channel: https://matrix.to/#/!tractor:matrix.org .. _matrix channel: https://matrix.to/#/!tractor:matrix.org
.. _pdb++: https://github.com/pdbpp/pdbpp .. _pdb++: https://github.com/pdbpp/pdbpp
@ -286,7 +331,6 @@ channel`_!
.. _trio docs: https://trio.readthedocs.io/en/latest/ .. _trio docs: https://trio.readthedocs.io/en/latest/
.. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ .. _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/ .. _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 .. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony
.. _async generators: https://www.python.org/dev/peps/pep-0525/ .. _async generators: https://www.python.org/dev/peps/pep-0525/
.. _trio-parallel: https://github.com/richardsheridan/trio-parallel .. _trio-parallel: https://github.com/richardsheridan/trio-parallel

View File

@ -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 # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # 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 # 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 # further. For a list of options available for each theme, see the
# documentation. # documentation.
html_theme_options = { html_theme_options = {
'logo': 'tractor_logo_side.svg', # 'logo': 'tractor_logo_side.svg',
'description': 'Structured concurrent "actors"', # 'description': 'Structured concurrent "actors"',
'github_user': 'goodboy', "repository_url": "https://github.com/goodboy/tractor",
'github_repo': 'tractor', "use_repository_button": True,
"home_page_in_toc": False,
"show_toc_level": 1,
"path_to_docs": "docs",
} }
html_sidebars = { html_sidebars = {
"**": [ "**": [
'logo.html', "sbt-sidebar-nav.html",
'github.html', "sidebar-search-bs.html",
'relations.html', # 'localtoc.html',
'searchbox.html' ],
] # 'logo.html',
# 'github.html',
# 'relations.html',
# 'searchbox.html'
# ]
} }
# doesn't seem to work?
# extra_navbar = "<p>nextttt-gennnnn</p>"
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, # 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, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".

View File

@ -3,12 +3,13 @@
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. contain the root `toctree` directive.
tractor ``tractor``
======= ===========
A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_. A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 1
:caption: Contents: :caption: Contents:
.. _actor model: https://en.wikipedia.org/wiki/Actor_model .. _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 .. _trio gitter channel: https://gitter.im/python-trio/general
.. contents::
Philosophy Philosophy
---------- ----------

View File

@ -1,2 +1,2 @@
sphinx sphinx
sphinx_typlog_theme sphinx_book_theme