コミット: d2a854f870d7453c8aa575e81013b5fa2405be6a - MESS (hg)

コミットメタ情報

• リビジョン: d2a854f870d7453c8aa575e81013b5fa2405be6a (tree)
• 日時: 2020-03-22 01:03:32
• 作者: Albert Mietus < albert AT mietus DOT nl >
• コミッター: Albert Mietus < albert AT mietus DOT nl >

ログメッセージ

Pub/Sub: concept done (draft)

変更サマリ

• modified: SoftwareCompetence/DesignWorkShops/PubSub/index.rst
• modified: conf.py
• add: SoftwareCompetence/DesignWorkShops/PubSub/concept/API.rst
• add: SoftwareCompetence/DesignWorkShops/PubSub/concept/PubSub-newspaper.puml
• add: SoftwareCompetence/DesignWorkShops/PubSub/concept/Use.rst
• add: SoftwareCompetence/DesignWorkShops/PubSub/concept/advantages.rst
• add: SoftwareCompetence/DesignWorkShops/PubSub/concept/index.rst
• add: _std_settings/static/SwBMnl-slides.css

差分

diff -r 9ec6ed103222 -r d2a854f870d7 SoftwareCompetence/DesignWorkShops/PubSub/concept/API.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SoftwareCompetence/DesignWorkShops/PubSub/concept/API.rst	Sat Mar 21 17:03:32 2020 +0100
@@ -0,0 +1,81 @@
+.. Copyright (C) 2020: ALbert Mietus.
+
+.. _PubSub_API:
+
+===============
+The Pub/Sub API
+===============
+
+As typical with *Design Patterns* there are many ways to implement it. Here we focus on the “Topic” approach. It
+decouples modules by defining a generic interface, and act as a kind of “man-in-the-middle”.
+
+Topic
+=====
+
+.. currentmodule:: pubsub
+
+.. class:: Topic
+
+   A :class:`~pubsub.Topic` is like a channel to distribute information (events), in a **Pub**/*Sub* environment.
+
+   This will decouple the :class:`pubsub.AbstractType.Publisher` from the :class:`pubsub.AbstractType.Subscriber` (in
+   both directions).
+
+   * On one side is a ``Publisher`` that provides ‘data’ (**value**’s, *events*, ...).
+   * The other side has ``Subscribers`` which subscribe to the topic (with **callbacks**).
+   * Both ``Publisher`` and ``Subscriber`` are abstract types; there is no contrete class (needed).
+   * Any module that calls :meth:`publish` is called a ``Publisher``; likewise a ``Subscriber`` is anyone calling
+     :meth:`subscribe`.
+   * Commonly there is only one ``Publisher`` (for a given Topic); that is not mandatory however.
+
+
+.. method:: Topic.publish(value, force=False):
+
+   This method is called by the ``Publisher``, whenever new **value** is to be shared. When **force** is `False`
+   (default), the ``value`` wil only be distributed when it differs from the previous value. To force distribution, set
+   **force** to `True`.
+
+.. method:: Topic.subscribe(callback):
+
+   This method is called by all ``Subscribers`` to *register* a **callback**, that is called on new ‘data’.
+
+   .. _PubSub_callback_signature:
+
+   The passed **callback** (any `callable`, like a :func:`~pubsub.AbstractType.callback_function_type`
+   :meth:`~pubsub.AbstractType.callback_method_type`) will be called when ‘data’ is available. It
+   has a signature like::
+
+     def callback([self,] value, topic):
+
+   Where **value** is the ‘data’ passed to :meth:`publish` and **topic** is the :class:`~pubsub.Topic`
+   instance itself.
+
+   When the callback is a method the `self` parameter is automagical remembered by python. For function-callbacks, leave
+   it out.
+
+Supporting types
+================
+
+.. currentmodule:: pubsub.AbstractType
+
+Both the ``Publisher`` and the ``Subscribers`` are *Abstract Types*.
+
+.. class:: Publisher
+
+   Any code that will call :meth:`pubsub.Topic.publish`. It can be a class, a module or just code ...
+
+.. class:: Subscriber
+
+   Everybody calling :meth:`pubsub.Topic.subscribe`. Typically, the :class:`Subscriber` has a **callback**
+   function/method too. See :ref:`PubSub_callback_demo` for an example.
+
+   Often, it has a method that act als callback.
+
+
+callbacks
+---------
+The generic signature for callbacks is simple:
+
+.. function:: callback_function_type(value, topic)
+.. method:: callback_method_type(self, value, topic)
+

diff -r 9ec6ed103222 -r d2a854f870d7 SoftwareCompetence/DesignWorkShops/PubSub/concept/PubSub-newspaper.puml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SoftwareCompetence/DesignWorkShops/PubSub/concept/PubSub-newspaper.puml	Sat Mar 21 17:03:32 2020 +0100
@@ -0,0 +1,42 @@
+@startuml
+hide footbox
+participant Publisher         as P
+participant You               as S1
+participant "Somebody"        as S2
+participant "Else"  as S3
+
+== Get your subscription ==
+
+P //-- S1    : Subscribe to newspaper
+...
+[--\ P : //news//
+activate P
+P -> S1     : Get your copy
+deactivate P
+
+== Everybody got its own **copy** of the //same// newspaper ==
+
+
+P //-- S2    : Another subscription
+P //-- S3    : Another subscription
+
+...
+[--\ P : //news//
+activate P
+P -> S1
+P -> S2
+P -> S3
+deactivate P
+
+== Until it is canceled ==
+
+P //-- S2    : unsubscribe
+...
+[--\ P : //news//
+activate P
+P -> S1
+P -> S3
+deactivate P
+
+
+@enduml

diff -r 9ec6ed103222 -r d2a854f870d7 SoftwareCompetence/DesignWorkShops/PubSub/concept/Use.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SoftwareCompetence/DesignWorkShops/PubSub/concept/Use.rst	Sat Mar 21 17:03:32 2020 +0100
@@ -0,0 +1,60 @@
+.. Copyright (C) 2020: ALbert Mietus.
+
+.. _PubSub_use:
+
+===
+Use
+===
+
+As typical with *Design Patterns* there are many ways to implement it. Here we focus on the “Topic” approach. It
+decouples modules by defining a generic interface and act as a kind of “man-in-the-middle”.
+
+Both the ``Publisher`` and the ``Subscribers`` share a common :class:`~pubsub.Topic` instance::
+
+  from pubsub import Topic
+  t = Topic("Just a demo")
+
+
+Publishers
+==========
+
+Publishing a value is very simple; assuming ``t`` is a :class:`pubsub.Topic` instance::
+
+  t.publish("Hello World")
+
+
+Subscribers
+===========
+
+Each subscriber should register a ``callback``, which will be called “automagical” when a new value is available::
+
+  t.subscribe(demo_cb)
+
+Where ``t`` is topic (an instance of :class:`pubsub.Topic`) and ``demo_cb`` is the *callback*. This can a function or other
+kind of callable. Multiple subscriptions are possible, by registering another::
+
+  t.subscribe(demo_oo_cb)
+
+.. _PubSub_callback_demo:
+
+callbacks
+---------
+
+A callback is a callable, that should process the new value. Basically, it is just a function (or method) with the
+correct signature. A trivial example is::
+
+  def demo_cb(value, topic):
+     print("Function-Demo:: Topic: %s has got the value: %s" %(topic, value))
+
+It can also be a method, when you prefer an OO-style::
+
+  class Demo:
+
+    def demo_oo_cb(self, val, topic):
+        print("Method-demo: I (%s) got '%s' from topic %s" %(self, val, topic))
+
+.. seealso::
+
+   * :class:`pubsub.AbstractType.Publisher`
+   * :class:`pubsub.AbstractType.Subscriber`
+   * :ref:`CallBack Signature <PubSub_callback_signature>`

diff -r 9ec6ed103222 -r d2a854f870d7 SoftwareCompetence/DesignWorkShops/PubSub/concept/advantages.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SoftwareCompetence/DesignWorkShops/PubSub/concept/advantages.rst	Sat Mar 21 17:03:32 2020 +0100
@@ -0,0 +1,51 @@
+.. Copyright (C) 2020: ALbert Mietus.
+
+Advantages
+==========
+
+For software-engineers, Pub/Sub has many advantages. The most obvious one is *decoupling*, another one is *scaling*. It
+is also simple to :ref:`PubSub_use`.
+
+And, with Pub/Sub you will automatically use
+`‘Dependency Inversion’ <https://en.wikipedia.org/wiki/Dependency_inversion_principle>`_, one of the
+`SOLID <https://en.wikipedia.org/wiki/SOLID>`_ principles; as well as
+`‘Dependency Injection’ <https://en.wikipedia.org/wiki/Dependency_injection>`_, which often simplifies testing.
+
+
+Coupling
+--------
+
+By and lange, software-routines have to pass information. From one function to another, from one class to another, or
+from one module to some other module(s). Especially this latter case is annoying, when it is implemented by calling a
+method of that other module. Then, we speak about **tight** (and *static*) **coupling**: the module effectively can’t
+perform without the other. When that “other” module is a stable, generic *library*, it is often considered as
+acceptable. Although it can disturbed your (unit)-testing; by making it slow.
+
+But how about two modules, that are under construction?
+|BR|
+Then, both are not “stable” (as they might develop) and being depended on unstable modules is bad. You can’t test
+independently, you may need to revise when the other is updated, etc. Well you know the troubles ...
+
+To overcome this, the modules should be *uncoupled* or *lousily coupled*: Both modules are not allowed to call a
+function/method of the other one. (Which is easy:-). But still pass information; which might seen impossible at first.
+
+This is possible, as the modules do not dependent on each other; instead they both depend on the generic
+:class:`pubsub.Topic`, as we can see on the :ref:`next page<PubSub_use>`
+
+
+Scaling
+-------
+
+Now and then the same data is needed by multiple “consumers”. That number of “users” may even grow in future releases. A
+sensor-value, by example, that was initially only used in one or two routines, may becomes relevant input to many new,
+fancy features.
+
+Imagene a modules that handles (pushing) the brake. Initially it was only needed to slow down the car. Nowadays it will
+switch-off the cruise control, also. Perhaps, in the future, that same data might influence the volume of the radio; or is
+needed to automatically “e-call” 112, when there is an serious road accident. Or ...
+
+With Pub/Sub, it is easy to distribute  data to more and more modules. Even to modules that aren’t yet imagined when you
+write that sensor-routine! Your current module only has use :meth:`pubsub.Topic.publish`, and that future module can
+get that data using :meth:`pubsub.Topic.subscribe`; easy!
+
+

diff -r 9ec6ed103222 -r d2a854f870d7 SoftwareCompetence/DesignWorkShops/PubSub/concept/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SoftwareCompetence/DesignWorkShops/PubSub/concept/index.rst	Sat Mar 21 17:03:32 2020 +0100
@@ -0,0 +1,25 @@
+.. Copyright (C) 2020: ALbert Mietus.
+
+Introduction
+============
+
+An almost trivial example of PubSub is the daily newspaper:
+
+ Once you get an subscription, you automatically get each new publication.
+
+Typically, your are not the only one. The *same* ‘newspaper’ is send to all subscribers: everybody got his own
+*copy*. And, when somebody cancels his subscription all others still het there daily update.
+|BR|
+Also notice: your copy is undependent of that the neighbours. And, until you subscribe, the publisher does not know
+you.
+
+In software-engineering we call that **uncoupled** or *loosely coupled*; and that is great.
+
+
+.. uml:: PubSub-newspaper.puml
+
+.. toctree::
+
+   advantages
+   Use
+   API

diff -r 9ec6ed103222 -r d2a854f870d7 SoftwareCompetence/DesignWorkShops/PubSub/index.rst
--- a/SoftwareCompetence/DesignWorkShops/PubSub/index.rst	Thu Mar 19 11:04:20 2020 +0100
+++ b/SoftwareCompetence/DesignWorkShops/PubSub/index.rst	Sat Mar 21 17:03:32 2020 +0100
@@ -8,12 +8,12 @@
 
 .. sidebar:: **HighTech** vs *Gooogling*
 
-   When you search for `Pub/Sub`, you will find over 312M hits! Mostly about cloud-computing, and on how servers exchange
-   messages via a *‘broker’*.
+   When you search for `Pub/Sub`, you will find over 312M hits! Most are about cloud-computing and on how to exchange messages
+   between servers via a *‘broker’*.
    |BR|
-   Often it is infrastructure engenering based.
+   Often it is infrastructure engineering based.
 
-   This workshop isn’t about that. We focus on *Modern, Embedded Software Systems*: How can an (HighTech) Software Engineer use
+   This workshop isn’t about that. We focus on *Modern, Embedded Software Systems*: How can a (HighTech) Software Engineer use
    this pattern to create better software.
 
 
@@ -59,4 +59,4 @@
 
 .. seealso::
 
-   * ...
+   * https://mybinder.org/v2/gh/AlbertMietus/PyMess.ipython-notebools/master?filepath=%2FSoftwareCompetence%2FDesignWorkShops%2FPubSub%2FPubSub-demo.ipynb

diff -r 9ec6ed103222 -r d2a854f870d7 _std_settings/static/SwBMnl-slides.css
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/_std_settings/static/SwBMnl-slides.css	Sat Mar 21 17:03:32 2020 +0100
@@ -0,0 +1,33 @@
+/* SwBMnl-slides style for Juyiter/IPython "download as slides" ...
+   The custom.css file should import it as:
+   @import url("/_static/SwBMnl-slides.css");
+*/
+
+/* Gray slides on gray background with blue border*/
+.reveal .slide-background { background: #808080;}
+.reveal div.slides {
+    background: #c0c0c0;
+    border: 2px solid #000066;
+}
+
+/* Also gray slides in overview-mode. Highligh the current slide a bit */
+.reveal.overview .slides section { background: #808080;}
+.reveal.overview .slides section.present { background: #c0c0c0;     border: 2px solid #000066;}
+
+/* H1, H2 headers in blue; top aligned. H1 in gray backgroud. In contact with (gray, see bellow side)*/
+.reveal .slides h1 {
+    color: #000066; background: #808080;
+    margin-left: -0.5em; padding-left: 1em;
+    margin-top: -0.5em; padding-top: 0.5em; padding-bottom: 0.5em;
+}
+.reveal .slides h2 {
+    color: #000066;
+    margin-top: -0.5em; padding-top: 0.5em;
+}
+
+/* Slighly style the input "sidebar". Make the "Header" text-cell-promt gray; as sidebar, in contact with H1 (see above) */
+.reveal .prompt.input_prompt { border: 1px solid #808080; }
+.reveal div.text_cell .prompt.input_prompt { border: 1px solid #808080; background:#808080;}
+
+/* code section ...*/
+.reveal .slides section code {background: #808080; color: #000066;}

diff -r 9ec6ed103222 -r d2a854f870d7 conf.py
--- a/conf.py	Thu Mar 19 11:04:20 2020 +0100
+++ b/conf.py	Sat Mar 21 17:03:32 2020 +0100
@@ -54,4 +54,3 @@
         '**': [ 'recentposts.html', 'tagcloud.html', 'postcardHeader.html'],
     }
 
-html_static_path.append('_static')