Merge pull request #211 from goodboy/new_docs_polish
New docs theme, readme actors rant.docs_revamp
goodboy
GitHub
commit
e98302212a
|
|
@ -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
|
||||
|
|
|
|||
38
docs/conf.py
38
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 = "<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,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
|
|
|
|||
|
|
@ -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
|
||||
----------
|
||||
|
|
|
|||
|
|
@ -1,2 +1,2 @@
|
|||
sphinx
|
||||
sphinx_typlog_theme
|
||||
sphinx_book_theme
|
||||
|
|
|
|||
Loading…
Reference in New Issue