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_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
|
\end_layout
|
||||||
|
|
||||||
\begin_layout Standard
|
\begin_layout Standard
|
||||||
|
@ -32032,6 +31736,302 @@ Same as the
|
||||||
firmly built in.
|
firmly built in.
|
||||||
\end_layout
|
\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
|
\begin_layout Section
|
||||||
Scripting HOWTO
|
Scripting HOWTO
|
||||||
\begin_inset CommandInset label
|
\begin_inset CommandInset label
|
||||||
|
|
Loading…
Reference in New Issue