Files
ProcessControl/_book/01-part-i-calls.html
T

1241 lines
60 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
<meta charset="utf-8">
<meta name="generator" content="quarto-1.10.18">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title>2&nbsp; Part I — Start with what you already know – Process Control</title>
<style>
/* Default styles provided by pandoc.
** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
*/
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: 1.5em;}
div.column{flex: auto;}
@media screen {
div.columns{gap: min(4vw, 1.5em);}
div.column{overflow-x: auto;}
}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
ul.task-list li input[type="checkbox"] {
width: 0.8em;
margin: 0 0.8em 0.2em -1em; /* quarto-specific, see https://github.com/quarto-dev/quarto-cli/issues/4556 */
vertical-align: middle;
}
/* CSS for syntax highlighting */
html { -webkit-text-size-adjust: 100%; }
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
}
pre.numberSource { margin-left: 3em; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
</style>
<script src="site_libs/quarto-nav/quarto-nav.js"></script>
<script src="site_libs/quarto-nav/headroom.min.js"></script>
<script src="site_libs/clipboard/clipboard.min.js"></script>
<script src="site_libs/quarto-search/autocomplete.umd.js"></script>
<script src="site_libs/quarto-search/fuse.min.js"></script>
<script src="site_libs/quarto-search/quarto-search.js"></script>
<meta name="quarto:offset" content="./">
<link href="./02-part-ii-processes.html" rel="next">
<link href="./00-orientation.html" rel="prev">
<script src="site_libs/quarto-html/quarto.js" type="module"></script>
<script src="site_libs/quarto-html/tabsets/tabsets.js" type="module"></script>
<script src="site_libs/quarto-html/popper.min.js"></script>
<script src="site_libs/quarto-html/tippy.umd.min.js"></script>
<script src="site_libs/quarto-html/anchor.min.js"></script>
<link href="site_libs/quarto-html/tippy.css" rel="stylesheet">
<link href="site_libs/quarto-html/quarto-syntax-highlighting-7c68a30ea258f1cbeb56603bc0a48370.css" rel="stylesheet" id="quarto-text-highlighting-styles">
<script src="site_libs/bootstrap/bootstrap.min.js"></script>
<link href="site_libs/bootstrap/bootstrap-icons.css" rel="stylesheet">
<link href="site_libs/bootstrap/bootstrap-cfe7114cbc4adb2af5ff3a891545d7fa.min.css" rel="stylesheet" append-hash="true" id="quarto-bootstrap" data-mode="light">
<script src="site_libs/quarto-contrib/calc-exo-2.0.0/exo.js"></script>
<link href="site_libs/quarto-contrib/calc-exo-2.0.0/exo.css" rel="stylesheet">
<script src="site_libs/quarto-contrib/calc-quiz-1.0.0/quiz.js"></script>
<link href="site_libs/quarto-contrib/calc-quiz-1.0.0/quiz.css" rel="stylesheet">
<link href="site_libs/quarto-contrib/calc-further-1.0.0/further.css" rel="stylesheet">
<link href="site_libs/quarto-contrib/calc-latex-tables-1.0.0/latex-tables.css" rel="stylesheet">
<script src="site_libs/quarto-contrib/calc-notes-1.0.0/calc-notes.js"></script>
<link href="site_libs/quarto-contrib/calc-notes-1.0.0/theme.css" rel="stylesheet">
<link href="site_libs/quarto-contrib/calc-notes-1.0.0/high-contrast.css" rel="stylesheet">
<link href="site_libs/quarto-contrib/calc-notes-1.0.0/calc-notes.css" rel="stylesheet">
<link href="site_libs/quarto-contrib/calc-notes-1.0.0/narrow.css" rel="stylesheet">
<script src="site_libs/quarto-contrib/calc-glossary-2.0.0/glossary.js"></script>
<link href="site_libs/quarto-contrib/calc-glossary-2.0.0/glossary.css" rel="stylesheet">
<script id="quarto-search-options" type="application/json">{
"location": "sidebar",
"copy-button": false,
"collapse-after": 3,
"panel-placement": "start",
"type": "textbox",
"limit": 50,
"keyboard-shortcut": [
"f",
"/",
"s"
],
"show-item-context": false,
"language": {
"search-no-results-text": "No results",
"search-matching-documents-text": "matching documents",
"search-copy-link-title": "Copy link to search",
"search-hide-matches-text": "Hide additional matches",
"search-more-match-text": "more match in this document",
"search-more-matches-text": "more matches in this document",
"search-clear-button-title": "Clear",
"search-text-placeholder": "",
"search-detached-cancel-button-title": "Cancel",
"search-submit-button-title": "Submit",
"search-label": "Search"
}
}</script>
<style>html{ scroll-behavior: smooth; }</style>
<!-- Language switcher for the html output only (included in the <head>).
Each profile's sidebar translate menu links to the start page of the other
languages (_book/ English, _book/fr/, _book/de/). All three books share the
same file names and section ids (#sec-...), so a click is sent to the same
page and section of the other language instead.
Quarto's page scripts rewrite those links in the browser (to an absolute
address without index.html), and can do so after this script runs. So
nothing is attached to the links themselves: one capture-phase listener on
the document reads the link's final address at click time.
If a language has not been built, its pages do not exist:
the target is checked first and a short note is shown instead of a
"Not Found" page.
The language picked in the menu is remembered for a year in a cookie
(notes-lang, limited to the book's address). A later visit to a page in
another language goes straight to the same page in the remembered one; this
runs in the <head>, before anything is drawn. Not in the local preview
(file:, localhost), where the other languages may not be built. -->
<script>
(function () {
var CODE = { 'Deutsch': 'de', 'Français': 'fr', 'English': 'en' };
var ROOT_LANG = 'en'; // the language at the top of _book/
var COOKIE = 'notes-lang';
var NOTE = {
de: 'Diese Sprache ist hier noch nicht verfügbar.',
fr: 'Cette langue n’est pas encore disponible ici.',
en: 'This language is not available here yet.'
};
var here = (document.documentElement.lang || ROOT_LANG).slice(0, 2);
// the book's top folder: /…/fr/page.html -> /…/ ; /…/page.html -> /…/
var dir = location.pathname.replace(/[^\/]*$/, '');
var root = (here !== ROOT_LANG && dir.slice(-(here.length + 2)) === '/' + here + '/')
? dir.slice(0, -(here.length + 1)) : dir;
var page = location.pathname.slice(dir.length); // "" for a folder
function remembered() {
var m = document.cookie.match(/(?:^|;\s*)notes-lang=(de|fr|en)(?:;|$)/);
return m ? m[1] : null;
}
// path '/' on purpose: every book of these notes is served from one host,
// each under its own folder, so a language picked in any of them is the
// language all of them open in. A book hosted on its own would be no worse
// off -- the cookie simply has nothing else to reach.
var COOKIE_PATH = '/';
function remember(code) {
document.cookie = COOKIE + '=' + code + '; path=' + COOKIE_PATH
+ '; max-age=31536000; SameSite=Lax'
+ (location.protocol === 'https:' ? '; Secure' : '');
// a copy written under the book's own path by an earlier version would be
// the more specific one and would shadow the shared cookie for good
if (root !== COOKIE_PATH) {
document.cookie = COOKIE + '=; path=' + root + '; max-age=0';
}
}
// a returning reader lands in the language picked last time
var live = /^https?:$/.test(location.protocol)
&& !/^(localhost|127\.0\.0\.1|\[::1\])$/.test(location.hostname);
var wanted = remembered();
if (live && wanted && wanted !== here) {
location.replace(root + (wanted === ROOT_LANG ? '' : wanted + '/') + page
+ location.search + location.hash);
return;
}
function note() {
var lang = (document.documentElement.lang || 'en').slice(0, 2);
var box = document.createElement('div');
box.setAttribute('role', 'status');
box.className = 'i18n-note';
box.textContent = NOTE[lang] || NOTE.en;
box.style.cssText = 'position:fixed;left:50%;bottom:1.25rem;transform:translateX(-50%);'
+ 'max-width:min(34rem,calc(100vw - 2rem));padding:.6rem .9rem;border-radius:6px;'
+ 'background:#1f2328;color:#fff;font-size:.85rem;line-height:1.4;z-index:2000;'
// a status message, so it keeps its own dark surface in either mode; the
// hairline is the page's rule colour, invisible on a light page and an
// edge against a dark one, where the shadow alone no longer separates it
+ 'border:1px solid var(--calc-line,#444);'
+ 'box-shadow:0 4px 16px var(--calc-shadow,rgba(0,0,0,.25))';
document.body.appendChild(box);
setTimeout(function () { box.remove(); }, 7000);
}
function exists(url) {
return fetch(url, { method: 'HEAD', cache: 'no-store' })
.then(function (r) { return r.status !== 404; }, function () { return true; });
}
document.addEventListener('click', function (ev) {
if (ev.button !== 0 || ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
var a = ev.target.closest && ev.target.closest('a.sidebar-tools-main-item');
if (!a || !a.href) return;
var code = CODE[a.textContent.trim()];
if (!code) return; // some other tool link
ev.preventDefault();
// the language being read already: just remember it
if (code === here) { remember(code); return; }
var link = new URL(a.href, location.href);
var target_root = link.pathname.replace(/index\.html$/, ''); // "/" or "/fr/"
if (target_root.slice(-1) !== '/') target_root += '/';
var target = link.origin + target_root + (page || 'index.html');
if (location.protocol === 'file:' || !window.fetch) {
remember(code);
location.href = target + location.hash;
return;
}
// same page in the other language, else its start page, else explain
exists(target).then(function (ok) {
if (ok) { remember(code); location.href = target + location.hash; return; }
return exists(link.origin + target_root).then(function (rootOk) {
if (rootOk) { remember(code); location.href = link.origin + target_root; }
else note();
});
});
}, true);
})();
</script>
<style>:root {
--calc-furthercolor-src: #6B3FA0;
--calc-furthercolor: var(--calc-furthercolor-src);
}</style>
<style>:root {
--calc-notecolor-src: #B45309;
--calc-notecolor: var(--calc-notecolor-src);
}</style>
<script>(function (e) {
var KEY = 'notes-contrast', forced = false;
var picked = null;
try { picked = localStorage.getItem(KEY); } catch (err) {}
var q = null;
try { q = window.matchMedia && window.matchMedia('(prefers-contrast: more)'); } catch (err) {}
if (picked === 'more' || (picked !== 'normal' && (forced || (q && q.matches)))) {
e.classList.add('hc');
}
if (q) {
var f = function () {
var p = null;
try { p = localStorage.getItem(KEY); } catch (err) {}
if (p === null) e.classList.toggle('hc', forced || q.matches);
};
if (q.addEventListener) q.addEventListener('change', f);
else if (q.addListener) q.addListener(f);
}
})(document.documentElement);</script>
</head>
<body class="nav-sidebar docked quarto-light">
<div id="quarto-search-results"></div>
<header id="quarto-header" class="headroom fixed-top">
<nav class="quarto-secondary-nav">
<div class="container-fluid d-flex">
<button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
<i class="bi bi-layout-text-sidebar-reverse"></i>
</button>
<nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="./01-part-i-calls.html"><span class="chapter-number">2</span>&nbsp; <span class="chapter-title">Part I — Start with what you already know</span></a></li></ol></nav>
<a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
</a>
<button type="button" class="btn quarto-search-button" aria-label="Search" onclick="window.quartoOpenSearch();">
<i class="bi bi-search"></i>
</button>
</div>
</nav>
</header>
<!-- content -->
<div id="quarto-content" class="quarto-container page-columns page-rows-contents page-layout-article">
<!-- sidebar -->
<nav id="quarto-sidebar" class="sidebar collapse collapse-horizontal quarto-sidebar-collapse-item sidebar-navigation docked overflow-auto">
<div class="pt-lg-2 mt-2 text-left sidebar-header">
<div class="sidebar-title mb-0 py-0">
<a href="./">Process Control</a>
<div class="sidebar-tools-main tools-wide">
<div class="dropdown">
<a href="" title="" id="quarto-navigation-tool-dropdown-0" class="quarto-navigation-tool dropdown-toggle px-1" data-bs-toggle="dropdown" aria-expanded="false" role="link" aria-label=""><i class="bi bi-translate"></i></a>
<ul class="dropdown-menu" aria-labelledby="quarto-navigation-tool-dropdown-0">
<li>
<a class="dropdown-item sidebar-tools-main-item" href="./index.html">
English
</a>
</li>
<li>
<a class="dropdown-item sidebar-tools-main-item" href="./fr/index.html">
Français
</a>
</li>
<li>
<a class="dropdown-item sidebar-tools-main-item" href="./de/index.html">
Deutsch
</a>
</li>
</ul>
</div>
<a href="./Process-Control.pdf" title="Download PDF" class="quarto-navigation-tool px-1" aria-label="Download PDF"><i class="bi bi-file-pdf"></i></a>
<a href="" class="quarto-reader-toggle quarto-navigation-tool px-1" onclick="window.quartoToggleReader(); return false;" title="Toggle reader mode">
<div class="quarto-reader-toggle-btn">
<i class="bi"></i>
</div>
</a>
</div>
</div>
</div>
<div class="mt-2 flex-shrink-0 align-items-center">
<div class="sidebar-search">
<div id="quarto-search" class="" title="Search"></div>
</div>
</div>
<div class="sidebar-menu-container">
<ul class="list-unstyled mt-1">
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./index.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">About these notes</span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./00-orientation.html" class="sidebar-item-text sidebar-link">
<span class="menu-text"><span class="chapter-number">1</span>&nbsp; <span class="chapter-title">Step 0 — What this is about</span></span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./01-part-i-calls.html" class="sidebar-item-text sidebar-link active">
<span class="menu-text"><span class="chapter-number">2</span>&nbsp; <span class="chapter-title">Part I — Start with what you already know</span></span></a>
</div>
</li>
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./02-part-ii-processes.html" class="sidebar-item-text sidebar-link">
<span class="menu-text"><span class="chapter-number">3</span>&nbsp; <span class="chapter-title">Part II — Cross the process boundary</span></span></a>
</div>
</li>
<li class="sidebar-item sidebar-item-section">
<div class="sidebar-item-container">
<a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="false">
<span class="menu-text">Appendices</span></a>
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="false" aria-label="Toggle section">
<i class="bi bi-chevron-right ms-2"></i>
</a>
</div>
<ul id="quarto-sidebar-section-1" class="collapse list-unstyled sidebar-section depth1 ">
<li class="sidebar-item">
<div class="sidebar-item-container">
<a href="./glossary.html" class="sidebar-item-text sidebar-link">
<span class="menu-text">Glossary</span></a>
</div>
</li>
</ul>
</li>
</ul>
</div>
</nav>
<div id="quarto-sidebar-glass" class="quarto-sidebar-collapse-item" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"></div>
<!-- margin-sidebar -->
<div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
<nav id="TOC" role="doc-toc" class="toc-active">
<h2 id="toc-title">On this page</h2>
<ul>
<li><a href="#sec-step-1" id="toc-sec-step-1" class="nav-link active" data-scroll-target="#sec-step-1"><span class="header-section-number">2.1</span> Step 1 — Rock bottom: just call it</a></li>
<li><a href="#sec-step-2" id="toc-sec-step-2" class="nav-link" data-scroll-target="#sec-step-2"><span class="header-section-number">2.2</span> Step 2 — Three egoistic capabilities</a></li>
<li><a href="#sec-step-3" id="toc-sec-step-3" class="nav-link" data-scroll-target="#sec-step-3"><span class="header-section-number">2.3</span> Step 3 — Give every capability a mailbox</a></li>
<li><a href="#sec-steps-4-6" id="toc-sec-steps-4-6" class="nav-link" data-scroll-target="#sec-steps-4-6"><span class="header-section-number">2.4</span> Steps 4–6 — The three capabilities become egoistic</a></li>
<li><a href="#sec-step-7" id="toc-sec-step-7" class="nav-link" data-scroll-target="#sec-step-7"><span class="header-section-number">2.5</span> Step 7 — Enter the mediator</a></li>
<li><a href="#sec-step-8" id="toc-sec-step-8" class="nav-link" data-scroll-target="#sec-step-8"><span class="header-section-number">2.6</span> Step 8 — Ask again: who knows whom?</a></li>
<li><a href="#sec-step-9" id="toc-sec-step-9" class="nav-link" data-scroll-target="#sec-step-9"><span class="header-section-number">2.7</span> Step 9 — Why virtual threads?</a></li>
<li><a href="#sec-step-10" id="toc-sec-step-10" class="nav-link" data-scroll-target="#sec-step-10"><span class="header-section-number">2.8</span> Step 10 — Keep the services egoistic</a></li>
<li><a href="#sec-part-i-result" id="toc-sec-part-i-result" class="nav-link" data-scroll-target="#sec-part-i-result"><span class="header-section-number">2.9</span> What part I moved</a></li>
</ul>
</nav>
</div>
<!-- main -->
<main class="content" id="quarto-document-content">
<header id="title-block-header" class="quarto-title-block default">
<div class="quarto-title">
<h1 class="title"><span id="sec-part-i" class="quarto-section-identifier"><span class="chapter-number">2</span>&nbsp; <span class="chapter-title">Part I — Start with what you already know</span></span></h1>
</div>
<div class="quarto-title-meta">
</div>
</header>
<!-- MULTILINGUAL: see the comment at the top of index.qmd. -->
<p>Steps 1 to 10 stay inside one JVM. The system is built three times: as direct calls, as three capabilities that refuse to know each other, and as those same capabilities glued together by mediators. Nothing is distributed yet, and that is the point: the only thing that changes is who knows whom.</p>
<section id="sec-step-1" class="level2" data-number="2.1">
<h2 data-number="2.1" class="anchored" data-anchor-id="sec-step-1"><span class="header-section-number">2.1</span> Step 1 — Rock bottom: just call it</h2>
<p><code>ProceduralRot13.java</code> is the whole system in one compact source file: a loop that reads a line, and one statement that prints the rotated text.</p>
<div class="code-copy-outer-scaffold"><div class="sourceCode" id="cb1"><pre class="sourceCode java code-with-copy"><code class="sourceCode java"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> <span class="fu">main</span><span class="op">()</span> <span class="op">{</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a> <span class="cf">while</span> <span class="op">(</span><span class="kw">true</span><span class="op">)</span> <span class="op">{</span></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">var</span> text <span class="op">=</span> IO<span class="op">.</span><span class="fu">readln</span><span class="op">();</span></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a> <span class="cf">if</span> <span class="op">(</span>text <span class="op">==</span> <span class="kw">null</span><span class="op">)</span></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a> <span class="cf">return</span><span class="op">;</span></span>
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a> IO<span class="op">.</span><span class="fu">println</span><span class="op">(</span><span class="fu">rot13</span><span class="op">(</span>text<span class="op">));</span></span>
<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a> <span class="op">}</span></span>
<span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></div>
<p><code>IO.readln()</code> stands on its own line, but <code>rot13(text)</code> is not a step of its own: it is called <em>inside</em> the argument of <code>IO.println</code>. Neither <code>rot13</code> nor <code>IO.println</code> knows anything about the other. The one that knows both is <code>main()</code>, which names them and fixes their order.</p>
<p>What <code>main()</code> knows about <code>rot13</code>: that it exists, how to invoke it (a bare name, both live in the same implicitly generated class), what argument it takes, what it returns, that it is available <em>right now</em>, and that execution continues after it returns. It does not know how <code>rot13</code> is implemented — that is the one thing it can ignore.</p>
<p>The availability guarantee is worth naming, because it disappears later: <code>main()</code> and <code>rot13</code> are two methods of one already-loaded class, called on the same thread, in the same process. Nothing has to be started first, no message travels anywhere, no listener has to be subscribed.</p>
<p><strong>Observed:</strong> typing a line prints it rotated; <code>Ctrl+D</code> ends the program silently, because <code>IO.readln()</code> returns <code>null</code> and <code>main()</code> returns.</p>
<div id="fig-direct-calls" class="flow-figure quarto-float quarto-figure quarto-figure-center anchored">
<figure class="quarto-float quarto-float-fig figure">
<div aria-describedby="fig-direct-calls-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
<img src="figures/direct-calls-en.svg" class="flow-figure img-fluid figure-img">
</div>
<figcaption class="quarto-float-caption-bottom quarto-float-caption quarto-float-fig" id="fig-direct-calls-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
Figure&nbsp;2.1: The procedural version. The wiring is written into the code: <code>main()</code> names all three parts and fixes their order.
</figcaption>
</figure>
</div>
</section>
<section id="sec-step-2" class="level2" data-number="2.2">
<h2 data-number="2.2" class="anchored" data-anchor-id="sec-step-2"><span class="header-section-number">2.2</span> Step 2 — Three egoistic capabilities</h2>
<p>An <strong>egoistic</strong> component says: I know what I can do, what data I accept and what data I produce — and I would rather not know the business process around me. Concretely, <code>ConsoleIn</code> must not contain <code>rot13(...)</code>, and <code>ROT13</code> must not contain <code>consoleOut(...)</code>.</p>
<p>Removing those calls immediately creates a problem, best put as a question: if nobody knows anybody, <strong>who makes this into a system?</strong> Note what the question does <em>not</em> say: the knowledge is not gone, it has to go somewhere else. Two connections are missing, not one — <code>ConsoleIn ↔︎ ROT13</code> and <code>ROT13 ↔︎ ConsoleOut</code>.</p>
</section>
<section id="sec-step-3" class="level2" data-number="2.3">
<h2 data-number="2.3" class="anchored" data-anchor-id="sec-step-3"><span class="header-section-number">2.3</span> Step 3 — Give every capability a mailbox</h2>
<p>The smallest mechanism for the missing connections: a message and a named queue.</p>
<div class="code-copy-outer-scaffold"><div class="sourceCode" id="cb2"><pre class="sourceCode java code-with-copy"><code class="sourceCode java"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">record</span> <span class="fu">Message</span><span class="op">(</span><span class="bu">String</span> type<span class="op">,</span> <span class="bu">String</span> value<span class="op">)</span> <span class="op">{}</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="bu">Map</span><span class="op">&lt;</span><span class="bu">String</span><span class="op">,</span> <span class="bu">BlockingQueue</span><span class="op">&lt;</span>Message<span class="op">&gt;&gt;</span> mailboxes <span class="op">=</span> <span class="kw">new</span> <span class="bu">ConcurrentHashMap</span><span class="op">&lt;&gt;();</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="bu">BlockingQueue</span><span class="op">&lt;</span>Message<span class="op">&gt;</span> <span class="fu">mailbox</span><span class="op">(</span><span class="bu">String</span> name<span class="op">)</span> <span class="op">{</span></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a> <span class="cf">return</span> mailboxes<span class="op">.</span><span class="fu">computeIfAbsent</span><span class="op">(</span>name<span class="op">,</span> _ <span class="op">-&gt;</span> <span class="kw">new</span> <span class="bu">LinkedBlockingQueue</span><span class="op">&lt;&gt;());</span></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></div>
<p>These are <strong>mailboxes</strong>, not topics, and the distinction is worth insisting on: if two readers call <code>take()</code> on the same mailbox, they compete — each message goes to exactly <em>one</em> of them and is not copied to both. A topic, in Publish/Subscribe, would hand every subscriber its own copy. One reader per message is enough for now, and the limitation is kept on purpose: it is what makes it clear later what Publish/Subscribe actually adds.</p>
</section>
<section id="sec-steps-4-6" class="level2" data-number="2.4">
<h2 data-number="2.4" class="anchored" data-anchor-id="sec-steps-4-6"><span class="header-section-number">2.4</span> Steps 4–6 — The three capabilities become egoistic</h2>
<p>Each capability now touches only its own mailbox names:</p>
<table class="caption-top table">
<thead>
<tr class="header">
<th>Capability</th>
<th>reads</th>
<th>writes</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>ConsoleIn</td>
<td>the keyboard</td>
<td><code>consoleIn.outbox</code></td>
</tr>
<tr class="even">
<td>ROT13</td>
<td><code>rot13.inbox</code></td>
<td><code>rot13.outbox</code></td>
</tr>
<tr class="odd">
<td>ConsoleOut</td>
<td><code>consoleOut.inbox</code></td>
<td>the console</td>
</tr>
</tbody>
</table>
<p>No capability contains the name of another, and that is exactly the result: three nicely isolated capabilities that do absolutely nothing together. Nothing moves a message from <code>consoleIn.outbox</code> to <code>rot13.inbox</code>, or from <code>rot13.outbox</code> to <code>consoleOut.inbox</code>.</p>
</section>
<section id="sec-step-7" class="level2" data-number="2.5">
<h2 data-number="2.5" class="anchored" data-anchor-id="sec-step-7"><span class="header-section-number">2.5</span> Step 7 — Enter the mediator</h2>
<p>The smallest possible glue: a loop that takes from one mailbox and puts into another, knowing nothing about what travels through it.</p>
<div class="code-copy-outer-scaffold"><div class="sourceCode" id="cb3"><pre class="sourceCode java code-with-copy"><code class="sourceCode java"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> <span class="fu">mediate</span><span class="op">(</span><span class="bu">String</span> from<span class="op">,</span> <span class="bu">String</span> to<span class="op">)</span> <span class="op">{</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a> <span class="cf">while</span> <span class="op">(</span><span class="kw">true</span><span class="op">)</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a> <span class="fu">mailbox</span><span class="op">(</span>to<span class="op">).</span><span class="fu">put</span><span class="op">(</span><span class="fu">mailbox</span><span class="op">(</span>from<span class="op">).</span><span class="fu">take</span><span class="op">());</span></span>
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></div>
<p><code>main()</code> starts five virtual threads: the three capabilities, plus two mediators whose routes are given as arguments — <code>consoleIn.outbox → rot13.inbox</code> and <code>rot13.outbox → consoleOut.inbox</code>.</p>
<p><strong>Observed:</strong> <code>Hello World</code> in, <code>Uryyb Jbeyq</code> out, exactly as in step 1. But <code>Ctrl+D</code> no longer ends the program. ConsoleIn’s thread <em>returns</em> (it does not loop), and the other four threads sit blocked in <code>take()</code> on empty mailboxes, using no CPU. What actually keeps the process alive is the last line of <code>main()</code>, <code>Thread.currentThread().join()</code>: the main thread waits for itself, which can never finish. Virtual threads are daemon threads, so those four waiting threads would not have kept the JVM running on their own.</p>
<div id="fig-mailboxes-jvm" class="flow-figure quarto-float quarto-figure quarto-figure-center anchored">
<figure class="quarto-float quarto-float-fig figure">
<div aria-describedby="fig-mailboxes-jvm-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
<img src="figures/mailboxes-jvm-en.svg" class="flow-figure img-fluid figure-img">
</div>
<figcaption class="quarto-float-caption-bottom quarto-float-caption quarto-float-fig" id="fig-mailboxes-jvm-caption-0ceaefa1-69ba-4598-a22c-09a6ac19f8ca">
Figure&nbsp;2.2: The mediated version inside one JVM. In the web version, <strong>Play</strong> walks one message through all eight hops.
</figcaption>
</figure>
</div>
</section>
<section id="sec-step-8" class="level2" data-number="2.6">
<h2 data-number="2.6" class="anchored" data-anchor-id="sec-step-8"><span class="header-section-number">2.6</span> Step 8 — Ask again: who knows whom?</h2>
<p>Does ConsoleIn know ROT13? No.&nbsp;Does ROT13 know ConsoleIn or ConsoleOut? No.&nbsp;Has the topology disappeared? No — it sits in the two <code>mediate(...)</code> calls inside <code>main()</code>.</p>
<p>This is the first major result:</p>
<blockquote class="blockquote">
<p><strong>Decoupling often does not make knowledge disappear. It moves knowledge to where it belongs.</strong></p>
</blockquote>
<p>The capability “ROT13 transforms text” belongs to ROT13. The topology <code>ConsoleIn → ROT13 → ConsoleOut</code> belongs to system composition. What changed since step 1 is not that the wiring left <code>main()</code> — it is still there — but that it is no longer written <em>inside</em> a capability. It is now data: two pairs of mailbox names. Rewiring touches those two lines and no capability at all.</p>
</section>
<section id="sec-step-9" class="level2" data-number="2.7">
<h2 data-number="2.7" class="anchored" data-anchor-id="sec-step-9"><span class="header-section-number">2.7</span> Step 9 — Why virtual threads?</h2>
<p>Five loops now wait indefinitely: the keyboard, <code>rot13.inbox</code>, <code>consoleOut.inbox</code> and the two mediators’ sources. Virtual threads are simply the cheap Java way to let five waits happen at once inside one JVM.</p>
<p>They are an implementation convenience, not an architecture. The architecture — who knows whom, and where the wiring lives — is in the mailbox names, not in the threads. The evidence for the separation: the same architecture will run as separate processes in step 11, with no threads shared between the parts.</p>
</section>
<section id="sec-step-10" class="level2" data-number="2.8">
<h2 data-number="2.8" class="anchored" data-anchor-id="sec-step-10"><span class="header-section-number">2.8</span> Step 10 — Keep the services egoistic</h2>
<p>The obvious shortcut: the first mediator only copies messages unchanged, so why not delete it and let ROT13 <code>take()</code> from <code>consoleIn.outbox</code> directly?</p>
<p>Because ROT13 would then contain the name <code>consoleIn.outbox</code>, which means it would know that ConsoleIn exists and where it publishes. The topology would move <em>into</em> ROT13, and ROT13 would stop being an egoistic capability. The test that makes this concrete: suppose the input comes from a new <code>FileIn</code> capability publishing to <code>fileIn.outbox</code>.</p>
<table class="caption-top table">
<thead>
<tr class="header">
<th></th>
<th>with the mediator</th>
<th>with the shortcut</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>what changes</td>
<td>one argument of the mediator</td>
<td><code>runRot13</code> itself</td>
</tr>
<tr class="even">
<td>who is touched</td>
<td>no capability</td>
<td>ROT13, whose job did not change</td>
</tr>
</tbody>
</table>
<p>The price is worth stating plainly: this design may look indirect — even a little odd. There is another way to keep services egoistic <em>without</em> a mediator in every message’s path, and it comes later.</p>
</section>
<section id="sec-part-i-result" class="level2" data-number="2.9">
<h2 data-number="2.9" class="anchored" data-anchor-id="sec-part-i-result"><span class="header-section-number">2.9</span> What part I moved</h2>
<table class="caption-top table">
<colgroup>
<col style="width: 33%">
<col style="width: 33%">
<col style="width: 33%">
</colgroup>
<thead>
<tr class="header">
<th>stage</th>
<th>where the topology lives</th>
<th>who could rewire it</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>step 1</td>
<td>inside the capability code (<code>IO.println(rot13(text))</code>)</td>
<td>whoever edits that code</td>
</tr>
<tr class="even">
<td>steps 7–8</td>
<td>in <code>main()</code>, as pairs of mailbox names</td>
<td>whoever edits <code>main()</code></td>
</tr>
</tbody>
</table>
<p>Functionality: unchanged. Lines of code: more. Parts that know each other: none. That is the trade everything that follows keeps testing.</p>
</section>
</main> <!-- /main -->
<!-- figures/flow-player.html -- the web version's interactive diagrams.
Injected at the end of <body> by include-in-header's sibling
include-after-body in _quarto.yml, so it is a no-op on a page that holds
no img.flow-figure.
A chapter writes an ordinary Quarto figure and adds the class:
![caption](figures/mailboxes-jvm-@tr{langcode}){#fig-x .flow-figure}
That keeps the PDF and the no-JavaScript case working: the built svg is
already the whole picture. Here the image is fetched, inlined, and given
a play bar that walks a message through the mailboxes, one hop per
[data-flow] edge of the svg, highlighting the [data-flow-node] each hop
ends at. Colours are diagram.css's, so the two stay in step. -->
<style>
.flow-wrap { margin: 0; }
.flow-wrap svg { width: 100%; height: auto; display: block; }
.flow-token { fill: #8a5a08; stroke: #fbfcfd; stroke-width: 1.2; }
.flow-wrap .flow-on .box,
.flow-wrap .flow-on .box-plain,
.flow-wrap .flow-on .box-accent { stroke-width: 3; }
.flow-wrap .flow-done { stroke: #8a5a08; }
.flow-bar {
display: flex; align-items: center; gap: .5rem; flex-wrap: wrap;
max-width: 100%; margin: .45rem 0 0;
}
.flow-bar button {
font: inherit; font-size: .82rem; padding: .18rem .7rem; cursor: pointer;
border: 1px solid #dae0e8; border-radius: 999px;
background: #fbfcfd; color: #5a6879;
}
.flow-bar button:hover { border-color: #20666f; color: #20666f; }
.flow-bar button[disabled] { opacity: .45; cursor: default; }
.flow-status { font-size: .8rem; color: #5a6879; }
.flow-status b { color: #20666f; font-weight: 600; }
@media (prefers-color-scheme: dark) {
.flow-token { fill: #c99a3a; stroke: #161b22; }
.flow-bar button { background: #161b22; border-color: #30363d; color: #8b98a8; }
.flow-bar button:hover { border-color: #4c9aa5; color: #7fc4cf; }
.flow-status { color: #8b98a8; }
.flow-status b { color: #7fc4cf; }
}
</style>
<script>
(() => {
const images = document.querySelectorAll("img.flow-figure");
if (!images.length) return;
const LANG = (document.documentElement.lang || "en").slice(0, 2);
const WORDS = {
en: { play: "Play", pause: "Pause", step: "One hop", reset: "Reset",
idle: "the message has not been sent yet", done: "arrived" },
fr: { play: "Lancer", pause: "Pause", step: "Un saut", reset: "Réinitialiser",
idle: "le message n'est pas encore parti", done: "arrivé" },
de: { play: "Abspielen", pause: "Pause", step: "Ein Sprung", reset: "Zurücksetzen",
idle: "die Nachricht ist noch nicht unterwegs", done: "angekommen" },
};
const W = WORDS[LANG] || WORDS.en;
const STILL = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
const HOP = 620; // ms per hop
const label = (node) => {
const text = node && node.querySelector("text");
return text ? text.textContent.trim() : "";
};
async function upgrade(img) {
let svg;
try {
const response = await fetch(img.currentSrc || img.src);
if (!response.ok) return; // leave the plain image in place
const doc = new DOMParser().parseFromString(await response.text(), "image/svg+xml");
svg = doc.documentElement;
if (!svg || svg.nodeName !== "svg" || doc.querySelector("parsererror")) return;
} catch { return; } // file:// or offline: plain image
const edges = [...svg.querySelectorAll("[data-flow]")]
.sort((a, b) => Number(a.dataset.flow) - Number(b.dataset.flow));
if (!edges.length) return;
svg.removeAttribute("width");
svg.removeAttribute("height");
const wrap = document.createElement("div");
wrap.className = "flow-wrap";
wrap.appendChild(svg);
const bar = document.createElement("div");
bar.className = "flow-bar";
const make = (name) => {
const button = document.createElement("button");
button.type = "button";
button.textContent = W[name];
bar.appendChild(button);
return button;
};
const playButton = make("play");
const stepButton = make("step");
const resetButton = make("reset");
const status = document.createElement("span");
status.className = "flow-status";
bar.appendChild(status);
wrap.appendChild(bar);
img.hidden = true;
img.after(wrap);
const token = document.createElementNS("http://www.w3.org/2000/svg", "circle");
token.setAttribute("r", "6");
token.setAttribute("class", "flow-token");
token.style.display = "none";
svg.appendChild(token);
let at = 0; // hops already made
let playing = false;
let frame = null;
const nodeOf = (edge) =>
edge.dataset.flowTo
? svg.querySelector(`[data-flow-node="${edge.dataset.flowTo}"]`)
: null;
const say = () => {
if (at === 0) { status.textContent = W.idle; return; }
const here = label(nodeOf(edges[at - 1]));
status.innerHTML = `${at} / ${edges.length} — <b></b>`;
status.querySelector("b").textContent =
at === edges.length ? `${here} (${W.done})` : here;
};
const clear = () => {
svg.querySelectorAll(".flow-on").forEach((n) => n.classList.remove("flow-on"));
edges.forEach((e) => e.classList.remove("flow-done"));
};
const place = (edge, fraction) => {
const length = edge.getTotalLength();
const point = edge.getPointAtLength(length * fraction);
token.setAttribute("cx", point.x);
token.setAttribute("cy", point.y);
token.style.display = "";
};
function hop(then) {
const edge = edges[at];
if (!edge) { then && then(false); return; }
clear();
const arrive = () => {
edge.classList.add("flow-done");
const node = nodeOf(edge);
if (node) node.classList.add("flow-on");
at += 1;
say();
buttons();
then && then(at < edges.length);
};
if (STILL) { place(edge, 1); arrive(); return; }
const start = performance.now();
const tick = (now) => {
const done = Math.min((now - start) / HOP, 1);
place(edge, done);
if (done < 1) { frame = requestAnimationFrame(tick); } else { frame = null; arrive(); }
};
frame = requestAnimationFrame(tick);
}
function buttons() {
const end = at >= edges.length;
playButton.textContent = playing ? W.pause : W.play;
playButton.disabled = end && !playing;
stepButton.disabled = end || playing;
resetButton.disabled = at === 0 && !playing;
}
function stop() {
playing = false;
if (frame) { cancelAnimationFrame(frame); frame = null; }
buttons();
}
function run() {
if (at >= edges.length) at = 0;
playing = true;
buttons();
const next = (more) => {
if (!playing) return;
if (more) { hop(next); } else { stop(); }
};
hop(next);
}
playButton.addEventListener("click", () => (playing ? stop() : run()));
stepButton.addEventListener("click", () => { stop(); hop(); });
resetButton.addEventListener("click", () => {
stop();
at = 0;
clear();
token.style.display = "none";
say();
buttons();
});
say();
buttons();
}
images.forEach(upgrade);
})();
</script>
<script id="quarto-html-after-body" type="application/javascript">
window.document.addEventListener("DOMContentLoaded", function (event) {
const icon = "";
const anchorJS = new window.AnchorJS();
anchorJS.options = {
placement: 'right',
icon: icon
};
anchorJS.add('.anchored');
const isCodeAnnotation = (el) => {
for (const clz of el.classList) {
if (clz.startsWith('code-annotation-')) {
return true;
}
}
return false;
}
const onCopySuccess = function(e) {
// button target
const button = e.trigger;
// don't keep focus
button.blur();
// flash "checked"
button.classList.add('code-copy-button-checked');
var currentTitle = button.getAttribute("title");
button.setAttribute("title", "Copied!");
let tooltip;
if (window.bootstrap) {
button.setAttribute("data-bs-toggle", "tooltip");
button.setAttribute("data-bs-placement", "left");
button.setAttribute("data-bs-title", "Copied!");
tooltip = new bootstrap.Tooltip(button,
{ trigger: "manual",
customClass: "code-copy-button-tooltip",
offset: [0, -8]});
tooltip.show();
}
setTimeout(function() {
if (tooltip) {
tooltip.hide();
button.removeAttribute("data-bs-title");
button.removeAttribute("data-bs-toggle");
button.removeAttribute("data-bs-placement");
}
button.setAttribute("title", currentTitle);
button.classList.remove('code-copy-button-checked');
}, 1000);
// clear code selection
e.clearSelection();
}
const getTextToCopy = function(trigger) {
const outerScaffold = trigger.parentElement.cloneNode(true);
const codeEl = outerScaffold.querySelector('code');
for (const childEl of codeEl.children) {
if (isCodeAnnotation(childEl)) {
childEl.remove();
}
}
return codeEl.innerText;
}
const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
text: getTextToCopy
});
clipboard.on('success', onCopySuccess);
if (window.document.getElementById('quarto-embedded-source-code-modal')) {
const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
text: getTextToCopy,
container: window.document.getElementById('quarto-embedded-source-code-modal')
});
clipboardModal.on('success', onCopySuccess);
}
var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
var mailtoRegex = new RegExp(/^mailto:/);
var filterRegex = new RegExp('/' + window.location.host + '/');
var isInternal = (href) => {
return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
}
// Inspect non-navigation links and adorn them if external
var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
for (var i=0; i<links.length; i++) {
const link = links[i];
if (!isInternal(link.href)) {
// undo the damage that might have been done by quarto-nav.js in the case of
// links that we want to consider external
if (link.dataset.originalHref !== undefined) {
link.href = link.dataset.originalHref;
}
// target, if specified
link.setAttribute("target", "_blank");
if (link.getAttribute("rel") === null) {
link.setAttribute("rel", "noopener");
}
}
}
function tippyHover(el, contentFn, onTriggerFn, onUntriggerFn) {
const config = {
allowHTML: true,
maxWidth: 500,
delay: 100,
arrow: false,
appendTo: function(el) {
return el.parentElement;
},
interactive: true,
interactiveBorder: 10,
theme: 'quarto',
placement: 'bottom-start',
};
if (contentFn) {
config.content = contentFn;
}
if (onTriggerFn) {
config.onTrigger = onTriggerFn;
}
if (onUntriggerFn) {
config.onUntrigger = onUntriggerFn;
}
window.tippy(el, config);
}
const noterefs = window.document.querySelectorAll('a[role="doc-noteref"]');
for (var i=0; i<noterefs.length; i++) {
const ref = noterefs[i];
tippyHover(ref, function() {
// use id or data attribute instead here
let href = ref.getAttribute('data-footnote-href') || ref.getAttribute('href');
try { href = new URL(href).hash; } catch {}
const id = href.replace(/^#\/?/, "");
const note = window.document.getElementById(id);
if (note) {
return note.innerHTML;
} else {
return "";
}
});
}
const xrefs = window.document.querySelectorAll('a.quarto-xref');
const processXRef = (id, note) => {
// Strip column container classes
const stripColumnClz = (el) => {
el.classList.remove("page-full", "page-columns");
if (el.children) {
for (const child of el.children) {
stripColumnClz(child);
}
}
}
stripColumnClz(note)
if (id === null || id.startsWith('sec-')) {
// Special case sections, only their first couple elements
const container = document.createElement("div");
if (note.children && note.children.length > 2) {
container.appendChild(note.children[0].cloneNode(true));
for (let i = 1; i < note.children.length; i++) {
const child = note.children[i];
if (child.tagName === "P" && child.innerText === "") {
continue;
} else {
container.appendChild(child.cloneNode(true));
break;
}
}
if (window.Quarto?.typesetMath) {
window.Quarto.typesetMath(container);
}
return container.innerHTML
} else {
if (window.Quarto?.typesetMath) {
window.Quarto.typesetMath(note);
}
return note.innerHTML;
}
} else {
// Remove any anchor links if they are present
const anchorLink = note.querySelector('a.anchorjs-link');
if (anchorLink) {
anchorLink.remove();
}
if (window.Quarto?.typesetMath) {
window.Quarto.typesetMath(note);
}
if (note.classList.contains("callout")) {
return note.outerHTML;
} else {
return note.innerHTML;
}
}
}
for (var i=0; i<xrefs.length; i++) {
const xref = xrefs[i];
tippyHover(xref, undefined, function(instance) {
instance.disable();
let url = xref.getAttribute('href');
let hash = undefined;
if (url.startsWith('#')) {
hash = url;
} else {
try { hash = new URL(url).hash; } catch {}
}
if (hash) {
const id = hash.replace(/^#\/?/, "");
const note = window.document.getElementById(id);
if (note !== null) {
try {
const html = processXRef(id, note.cloneNode(true));
instance.setContent(html);
} finally {
instance.enable();
instance.show();
}
} else {
// See if we can fetch this
fetch(url.split('#')[0])
.then(res => res.text())
.then(html => {
const parser = new DOMParser();
const htmlDoc = parser.parseFromString(html, "text/html");
const note = htmlDoc.getElementById(id);
if (note !== null) {
const html = processXRef(id, note);
instance.setContent(html);
}
}).finally(() => {
instance.enable();
instance.show();
});
}
} else {
// See if we can fetch a full url (with no hash to target)
// This is a special case and we should probably do some content thinning / targeting
fetch(url)
.then(res => res.text())
.then(html => {
const parser = new DOMParser();
const htmlDoc = parser.parseFromString(html, "text/html");
const note = htmlDoc.querySelector('main.content');
if (note !== null) {
// This should only happen for chapter cross references
// (since there is no id in the URL)
// remove the first header
if (note.children.length > 0 && note.children[0].tagName === "HEADER") {
note.children[0].remove();
}
const html = processXRef(null, note);
instance.setContent(html);
}
}).finally(() => {
instance.enable();
instance.show();
});
}
}, function(instance) {
});
}
let selectedAnnoteEl;
const selectorForAnnotation = ( cell, annotation) => {
let cellAttr = 'data-code-cell="' + cell + '"';
let lineAttr = 'data-code-annotation="' + annotation + '"';
const selector = 'span[' + cellAttr + '][' + lineAttr + ']';
return selector;
}
const selectCodeLines = (annoteEl) => {
const doc = window.document;
const targetCell = annoteEl.getAttribute("data-target-cell");
const targetAnnotation = annoteEl.getAttribute("data-target-annotation");
const annoteSpan = window.document.querySelector(selectorForAnnotation(targetCell, targetAnnotation));
const lines = annoteSpan.getAttribute("data-code-lines").split(",");
const lineIds = lines.map((line) => {
return targetCell + "-" + line;
})
let top = null;
let height = null;
let parent = null;
if (lineIds.length > 0) {
//compute the position of the single el (top and bottom and make a div)
const el = window.document.getElementById(lineIds[0]);
top = el.offsetTop;
height = el.offsetHeight;
parent = el.parentElement.parentElement;
if (lineIds.length > 1) {
const lastEl = window.document.getElementById(lineIds[lineIds.length - 1]);
const bottom = lastEl.offsetTop + lastEl.offsetHeight;
height = bottom - top;
}
if (top !== null && height !== null && parent !== null) {
// cook up a div (if necessary) and position it
let div = window.document.getElementById("code-annotation-line-highlight");
if (div === null) {
div = window.document.createElement("div");
div.setAttribute("id", "code-annotation-line-highlight");
div.style.position = 'absolute';
parent.appendChild(div);
}
div.style.top = top - 2 + "px";
div.style.height = height + 4 + "px";
div.style.left = 0;
let gutterDiv = window.document.getElementById("code-annotation-line-highlight-gutter");
if (gutterDiv === null) {
gutterDiv = window.document.createElement("div");
gutterDiv.setAttribute("id", "code-annotation-line-highlight-gutter");
gutterDiv.style.position = 'absolute';
const codeCell = window.document.getElementById(targetCell);
const gutter = codeCell.querySelector('.code-annotation-gutter');
gutter.appendChild(gutterDiv);
}
gutterDiv.style.top = top - 2 + "px";
gutterDiv.style.height = height + 4 + "px";
}
selectedAnnoteEl = annoteEl;
}
};
const unselectCodeLines = () => {
const elementsIds = ["code-annotation-line-highlight", "code-annotation-line-highlight-gutter"];
elementsIds.forEach((elId) => {
const div = window.document.getElementById(elId);
if (div) {
div.remove();
}
});
selectedAnnoteEl = undefined;
};
// Handle positioning of the toggle
window.addEventListener(
"resize",
throttle(() => {
elRect = undefined;
if (selectedAnnoteEl) {
selectCodeLines(selectedAnnoteEl);
}
}, 10)
);
function throttle(fn, ms) {
let throttle = false;
let timer;
return (...args) => {
if(!throttle) { // first call gets through
fn.apply(this, args);
throttle = true;
} else { // all the others get throttled
if(timer) clearTimeout(timer); // cancel #2
timer = setTimeout(() => {
fn.apply(this, args);
timer = throttle = false;
}, ms);
}
};
}
// Attach click handler to the DT
const annoteDls = window.document.querySelectorAll('dt[data-target-cell]');
for (const annoteDlNode of annoteDls) {
annoteDlNode.addEventListener('click', (event) => {
const clickedEl = event.target;
if (clickedEl !== selectedAnnoteEl) {
unselectCodeLines();
const activeEl = window.document.querySelector('dt[data-target-cell].code-annotation-active');
if (activeEl) {
activeEl.classList.remove('code-annotation-active');
}
selectCodeLines(clickedEl);
clickedEl.classList.add('code-annotation-active');
} else {
// Unselect the line
unselectCodeLines();
clickedEl.classList.remove('code-annotation-active');
}
});
}
const findCites = (el) => {
const parentEl = el.parentElement;
if (parentEl) {
const cites = parentEl.dataset.cites;
if (cites) {
return {
el,
cites: cites.split(' ')
};
} else {
return findCites(el.parentElement)
}
} else {
return undefined;
}
};
var bibliorefs = window.document.querySelectorAll('a[role="doc-biblioref"]');
for (var i=0; i<bibliorefs.length; i++) {
const ref = bibliorefs[i];
const citeInfo = findCites(ref);
if (citeInfo) {
tippyHover(citeInfo.el, function() {
var popup = window.document.createElement('div');
citeInfo.cites.forEach(function(cite) {
var citeDiv = window.document.createElement('div');
citeDiv.classList.add('hanging-indent');
citeDiv.classList.add('csl-entry');
var biblioDiv = window.document.getElementById('ref-' + cite);
if (biblioDiv) {
citeDiv.innerHTML = biblioDiv.innerHTML;
}
popup.appendChild(citeDiv);
});
return popup.innerHTML;
});
}
}
});
</script>
<nav class="page-navigation">
<div class="nav-page nav-page-previous">
<a href="./00-orientation.html" class="pagination-link" aria-label="[Step 0 — What this is about]{.en}[Étape 0 — De quoi il s'agit]{.fr}[Schritt 0 — Worum es geht]{.de}">
<i class="bi bi-arrow-left-short"></i> <span class="nav-page-text"><span class="chapter-number">1</span>&nbsp; <span class="chapter-title">Step 0 — What this is about</span></span>
</a>
</div>
<div class="nav-page nav-page-next">
<a href="./02-part-ii-processes.html" class="pagination-link" aria-label="[Part II — Cross the process boundary]{.en}[Partie II — Franchir la frontière de processus]{.fr}[Teil II — Die Prozessgrenze überschreiten]{.de}">
<span class="nav-page-text"><span class="chapter-number">3</span>&nbsp; <span class="chapter-title">Part II — Cross the process boundary</span></span> <i class="bi bi-arrow-right-short"></i>
</a>
</div>
</nav>
</div> <!-- /content -->
<script src="site_libs/quarto-html/zenscroll-min.js"></script>
</body></html>