mirror of https://github.com/schoebel/mars
user-manual: move macro processor
This commit is contained in:
parent
0e22dca232
commit
3ad1f8b45e
|
@ -27477,302 +27477,6 @@ name "sec:The-macro-processor"
|
|||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
Troubleshooting
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
TBD: appendices....
|
||||
\end_layout
|
||||
|
||||
\begin_layout Part
|
||||
Old Structure (TO DISAPPEAR)
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
Quick Start Guide
|
||||
\end_layout
|
||||
|
||||
\begin_layout Section
|
||||
The State of MARS
|
||||
\begin_inset CommandInset label
|
||||
LatexCommand label
|
||||
name "sec:The-State-of"
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
In general, MARS tries to
|
||||
\emph on
|
||||
hide
|
||||
\emph default
|
||||
any network failures from you as best as it can.
|
||||
After a network problem, any internal low-level socket connections are
|
||||
|
||||
\emph on
|
||||
transparently
|
||||
\emph default
|
||||
tried to re-open ASAP, without need for sysadmin intervention.
|
||||
In difference to DRBD, network failures will
|
||||
\emph on
|
||||
not
|
||||
\emph default
|
||||
automatically alter the state of MARS, such as switching to
|
||||
\family typewriter
|
||||
disconnected
|
||||
\family default
|
||||
after a
|
||||
\family typewriter
|
||||
ko_timeout
|
||||
\family default
|
||||
or similar.
|
||||
From a high-level sysadmin viewpoint, communication may just take a very
|
||||
long time to succeed.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
When the behaviour of MARS is different from DRBD, it is usually intended
|
||||
as a feature.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
MARS is not only an
|
||||
\series bold
|
||||
asynchronous
|
||||
\series default
|
||||
system at block IO level, but also
|
||||
\series bold
|
||||
at control level
|
||||
\series default
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
This is
|
||||
\emph on
|
||||
necessary
|
||||
\emph default
|
||||
because in a widely distributed long-distance system running on slow or
|
||||
even temporarily failing networks, actions may take a long time, and there
|
||||
may be many actions
|
||||
\series bold
|
||||
started in parallel
|
||||
\series default
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
\begin_inset Graphics
|
||||
filename images/lightbulb_brightlit_benj_.png
|
||||
lyxscale 12
|
||||
scale 7
|
||||
|
||||
\end_inset
|
||||
|
||||
Synchronous concepts are generally not sufficient for expressing that.
|
||||
Because of inherent asynchronicity and of dynamic creation / joining of
|
||||
resources, it is neither possible to comprehensively depict a complex distribut
|
||||
ed MARS system, nor a comprehensive standalone snippet of MARS, as a finite
|
||||
state transition diagram
|
||||
\begin_inset Foot
|
||||
status open
|
||||
|
||||
\begin_layout Plain Layout
|
||||
Probably it could be possible to formally model MARS as a Petri net.
|
||||
However, complete Petri nets are tending to become very conplex, and to
|
||||
describe lots of low-level details.
|
||||
Expressing hierarchy, in a top-down fashion, is cumbersome.
|
||||
We find no clue in trying to do so.
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Although MARS tries to
|
||||
\emph on
|
||||
approximate
|
||||
\emph default
|
||||
/
|
||||
\emph on
|
||||
emulate
|
||||
\emph default
|
||||
the synchronous control behaviour of DRBD at the interface level (
|
||||
\family typewriter
|
||||
marsadm
|
||||
\family default
|
||||
) in many situations as best as it can, the
|
||||
\emph on
|
||||
internal
|
||||
\emph default
|
||||
control model is necessarily asynchronous.
|
||||
As an experiencend sysadmin, you will be curious how it works in principle.
|
||||
When you know something about it, you will no longer be surprised when
|
||||
some (detail) behaviour is different from DRBD.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
The general principle is an asynchronous 2-edge handshake protocol, which
|
||||
is used almost everywhere in MARS:
|
||||
\begin_inset Separator latexpar
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
\noindent
|
||||
\align center
|
||||
\begin_inset Graphics
|
||||
filename images/handshake.fig
|
||||
width 80col%
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
We have a binary todo switch, which can be either in state
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
on
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
or
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
off
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
.
|
||||
In addition, we have an actual response indicator, which is similar to
|
||||
an LED indicating the actual status.
|
||||
In our example, we imagine that both are used for controlling a big ventilator,
|
||||
having a huge inert mass.
|
||||
Imagine a big machine from a power plant, which is as tall as a human.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
We start in a situation where the binary switch is off, and the ventilator
|
||||
is stopped.
|
||||
At point 1, we turn on the switch.
|
||||
At that moment, a big contactor will sound like
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
zonggg
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
, and a big motor will start to hum.
|
||||
At first you won't hear anything else.
|
||||
It will take a while, say 1 minute, until the big wheel will have reached
|
||||
its final operating RPM, due to the huge inert mass.
|
||||
During that spin-up, the lights in your room will become slightly darker.
|
||||
When having reached the full RPM at point 2, your workplace will then be
|
||||
noisier, but in exchange your room lights will be back at ordinary strength,
|
||||
and the actual response LED will start to lit in order to indicate that
|
||||
the big fan is now operational.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Assume we want to turn the system off.
|
||||
When turning the todo switch to
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
off
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
at point 3, first nothing will seem to happen at all.
|
||||
The big wheel will keep spinning due to its heavy inert mass, and the RPM
|
||||
as well as the sound will go down only slowly.
|
||||
During spin-down, the actual response LED will stay illuminated, in order
|
||||
to warn you that you should not touch the wheel, otherwise you may get
|
||||
injuried
|
||||
\begin_inset Foot
|
||||
status open
|
||||
|
||||
\begin_layout Plain Layout
|
||||
Notice that it is only safe to access the wheel when
|
||||
\emph on
|
||||
both
|
||||
\emph default
|
||||
the switch and the LED are off.
|
||||
Conversely, if at least one of them is on, something is going on inside
|
||||
the machine.
|
||||
Transferred to MARS: always look at
|
||||
\emph on
|
||||
both
|
||||
\emph default
|
||||
the todo switch and the correponding actual indicator in order to not miss
|
||||
something.
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
.
|
||||
The LED will only go off after, say, 2 minutes, when the wheel has actually
|
||||
stopped at point 4.
|
||||
After that, the cycle may potentially start over again.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
As you can see, all four possible cartesian product combinations between
|
||||
two boolean values are occurring in the diagram.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
The same handshake protocol is used in MARS for communication between userspace
|
||||
and kernelspace, as well as for communication in the widely distributed
|
||||
system.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
Basic Working Principle
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Even if you are impatient, please read this chapter.
|
||||
At the
|
||||
\emph on
|
||||
surface
|
||||
\emph default
|
||||
, MARS appears to be very similar to DRBD.
|
||||
It looks like almost being a drop-in replacement for DRBD.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
When taking this naïvely, you could easily step into some trivial pitfalls,
|
||||
because the internal working principle of MARS is totally different from
|
||||
DRBD.
|
||||
Please forget (almost) anything you already know about the internal working
|
||||
principles of DRBD, and look at the very different working principles of
|
||||
MARS.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
The Macro Processor
|
||||
\begin_inset CommandInset label
|
||||
LatexCommand label
|
||||
name "chap:The-Macro-Processor"
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
|
@ -32032,6 +31736,302 @@ Same as the
|
|||
firmly built in.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
Troubleshooting
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
TBD: appendices....
|
||||
\end_layout
|
||||
|
||||
\begin_layout Part
|
||||
Old Structure (TO DISAPPEAR)
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
Quick Start Guide
|
||||
\end_layout
|
||||
|
||||
\begin_layout Section
|
||||
The State of MARS
|
||||
\begin_inset CommandInset label
|
||||
LatexCommand label
|
||||
name "sec:The-State-of"
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
In general, MARS tries to
|
||||
\emph on
|
||||
hide
|
||||
\emph default
|
||||
any network failures from you as best as it can.
|
||||
After a network problem, any internal low-level socket connections are
|
||||
|
||||
\emph on
|
||||
transparently
|
||||
\emph default
|
||||
tried to re-open ASAP, without need for sysadmin intervention.
|
||||
In difference to DRBD, network failures will
|
||||
\emph on
|
||||
not
|
||||
\emph default
|
||||
automatically alter the state of MARS, such as switching to
|
||||
\family typewriter
|
||||
disconnected
|
||||
\family default
|
||||
after a
|
||||
\family typewriter
|
||||
ko_timeout
|
||||
\family default
|
||||
or similar.
|
||||
From a high-level sysadmin viewpoint, communication may just take a very
|
||||
long time to succeed.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
When the behaviour of MARS is different from DRBD, it is usually intended
|
||||
as a feature.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
MARS is not only an
|
||||
\series bold
|
||||
asynchronous
|
||||
\series default
|
||||
system at block IO level, but also
|
||||
\series bold
|
||||
at control level
|
||||
\series default
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
This is
|
||||
\emph on
|
||||
necessary
|
||||
\emph default
|
||||
because in a widely distributed long-distance system running on slow or
|
||||
even temporarily failing networks, actions may take a long time, and there
|
||||
may be many actions
|
||||
\series bold
|
||||
started in parallel
|
||||
\series default
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
\begin_inset Graphics
|
||||
filename images/lightbulb_brightlit_benj_.png
|
||||
lyxscale 12
|
||||
scale 7
|
||||
|
||||
\end_inset
|
||||
|
||||
Synchronous concepts are generally not sufficient for expressing that.
|
||||
Because of inherent asynchronicity and of dynamic creation / joining of
|
||||
resources, it is neither possible to comprehensively depict a complex distribut
|
||||
ed MARS system, nor a comprehensive standalone snippet of MARS, as a finite
|
||||
state transition diagram
|
||||
\begin_inset Foot
|
||||
status open
|
||||
|
||||
\begin_layout Plain Layout
|
||||
Probably it could be possible to formally model MARS as a Petri net.
|
||||
However, complete Petri nets are tending to become very conplex, and to
|
||||
describe lots of low-level details.
|
||||
Expressing hierarchy, in a top-down fashion, is cumbersome.
|
||||
We find no clue in trying to do so.
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Although MARS tries to
|
||||
\emph on
|
||||
approximate
|
||||
\emph default
|
||||
/
|
||||
\emph on
|
||||
emulate
|
||||
\emph default
|
||||
the synchronous control behaviour of DRBD at the interface level (
|
||||
\family typewriter
|
||||
marsadm
|
||||
\family default
|
||||
) in many situations as best as it can, the
|
||||
\emph on
|
||||
internal
|
||||
\emph default
|
||||
control model is necessarily asynchronous.
|
||||
As an experiencend sysadmin, you will be curious how it works in principle.
|
||||
When you know something about it, you will no longer be surprised when
|
||||
some (detail) behaviour is different from DRBD.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
The general principle is an asynchronous 2-edge handshake protocol, which
|
||||
is used almost everywhere in MARS:
|
||||
\begin_inset Separator latexpar
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
\noindent
|
||||
\align center
|
||||
\begin_inset Graphics
|
||||
filename images/handshake.fig
|
||||
width 80col%
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
We have a binary todo switch, which can be either in state
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
on
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
or
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
off
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
.
|
||||
In addition, we have an actual response indicator, which is similar to
|
||||
an LED indicating the actual status.
|
||||
In our example, we imagine that both are used for controlling a big ventilator,
|
||||
having a huge inert mass.
|
||||
Imagine a big machine from a power plant, which is as tall as a human.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
We start in a situation where the binary switch is off, and the ventilator
|
||||
is stopped.
|
||||
At point 1, we turn on the switch.
|
||||
At that moment, a big contactor will sound like
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
zonggg
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
, and a big motor will start to hum.
|
||||
At first you won't hear anything else.
|
||||
It will take a while, say 1 minute, until the big wheel will have reached
|
||||
its final operating RPM, due to the huge inert mass.
|
||||
During that spin-up, the lights in your room will become slightly darker.
|
||||
When having reached the full RPM at point 2, your workplace will then be
|
||||
noisier, but in exchange your room lights will be back at ordinary strength,
|
||||
and the actual response LED will start to lit in order to indicate that
|
||||
the big fan is now operational.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Assume we want to turn the system off.
|
||||
When turning the todo switch to
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
off
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
at point 3, first nothing will seem to happen at all.
|
||||
The big wheel will keep spinning due to its heavy inert mass, and the RPM
|
||||
as well as the sound will go down only slowly.
|
||||
During spin-down, the actual response LED will stay illuminated, in order
|
||||
to warn you that you should not touch the wheel, otherwise you may get
|
||||
injuried
|
||||
\begin_inset Foot
|
||||
status open
|
||||
|
||||
\begin_layout Plain Layout
|
||||
Notice that it is only safe to access the wheel when
|
||||
\emph on
|
||||
both
|
||||
\emph default
|
||||
the switch and the LED are off.
|
||||
Conversely, if at least one of them is on, something is going on inside
|
||||
the machine.
|
||||
Transferred to MARS: always look at
|
||||
\emph on
|
||||
both
|
||||
\emph default
|
||||
the todo switch and the correponding actual indicator in order to not miss
|
||||
something.
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
.
|
||||
The LED will only go off after, say, 2 minutes, when the wheel has actually
|
||||
stopped at point 4.
|
||||
After that, the cycle may potentially start over again.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
As you can see, all four possible cartesian product combinations between
|
||||
two boolean values are occurring in the diagram.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
The same handshake protocol is used in MARS for communication between userspace
|
||||
and kernelspace, as well as for communication in the widely distributed
|
||||
system.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
Basic Working Principle
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Even if you are impatient, please read this chapter.
|
||||
At the
|
||||
\emph on
|
||||
surface
|
||||
\emph default
|
||||
, MARS appears to be very similar to DRBD.
|
||||
It looks like almost being a drop-in replacement for DRBD.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
When taking this naïvely, you could easily step into some trivial pitfalls,
|
||||
because the internal working principle of MARS is totally different from
|
||||
DRBD.
|
||||
Please forget (almost) anything you already know about the internal working
|
||||
principles of DRBD, and look at the very different working principles of
|
||||
MARS.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
The Macro Processor
|
||||
\begin_inset CommandInset label
|
||||
LatexCommand label
|
||||
name "chap:The-Macro-Processor"
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Section
|
||||
Scripting HOWTO
|
||||
\begin_inset CommandInset label
|
||||
|
|
Loading…
Reference in New Issue