forked from dspinellis/dgsh
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
334 lines (308 loc) · 12.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<title>sgsh — scatter-gather shell</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<!-- Bootstrap -->
<link href="../../a/bootstrap/css/bootstrap.min.css" rel="stylesheet" />
<link href="../../a/bootstrap/css/bootstrap-responsive.min.css" rel="stylesheet" />
<link href="../../a/prettify/prettify.css" type="text/css" rel="stylesheet" />
<link href="../../a/dds-bstyle.css" rel="stylesheet" />
</head>
<body data-spy="scroll" data-target="#sidemenu">
<div class="top">sgsh dds</div>
<div class="row">
<div class="span4" id="sidemenu" >
<ul class="nav nav-list sidenav" data-spy="affix">
<li ><a href="#intro">Introduction</a></li>
<li>
<ul class="nav nav-list">
<li ><a href="#ipc">IPC</a></li>
<li ><a href="#syntax">Syntax</a></li>
</ul>
</li>
<li ><a href="#download">Downloading and installation</a></li>
<li ><a href="#debug">Debugging and profiling</a></li>
<li ><a href="#reference">Reference</a></li>
<li><a href="#examples">Examples</a></li>
<li>
<ul class="nav nav-list">
<!-- #!sh format-eg.sh -c -->
</ul>
</li>
</ul>
</div> <!-- span4 -->
<div class="span8">
<!-- About {{{1
================================================== -->
<section id="intro">
<div class="page-header">
<h1>sgsh — scatter-gather shell</h1>
</div>
<p>
The scatter gather shell, <em>sgsh</em>,
provides an expressive way to construct
sophisticated and efficient big data set and stream processing pipelines
using existing Unix tools as well as custom-built components.
It is a Unix-style shell allowing the specification of pipelines
with non-linear scatter-gather operations.
These form a directed acyclic process graph,
which is typically executed by multiple processor cores,
thus increasing the operation's processing throughput.
</p>
<p>
If you want to get a feeling on how <em>sgsh</em> works in practice,
skip right down to the <a href="#examples">examples</a> section.
</p>
</section> <!-- Introduction -->
<section id="ipc"> <!-- {{{2 -->
<h2>Inter-process communication</h2>
<p>
<em>Sgsh</em> provides three new ways
for expressing inter-process communication.
</p>
<dl class="dl-horizontal">
<dt>Scatter blocks</dt><dd> send the output of one pipeline ending
with <code>|{</code> into multiple pipelines beginning with <code>-|</code>.
The scatter block is terminated by <code>|}</code>.
Scatter interconnections are internally implemented through
automatically-named pipes, and a helper program,
<em>sgsh-tee</em>(1),
that distributes the data to multiple processes.
The scatter behavior can be modified by adding
<em>sgsh-tee</em>(1) flags after the <code>|{</code> symbol.
</dd>
<dt>Stores</dt><dd> are named as <code>store:</code><em>name</em>.
These allow the storage of a data stream's
last record (or of a specified window of records) into a named buffer.
This record can be later retrieved asynchronously by one or more readers.
Data can be piped into a store or out of a store, or it can be read
using the shell's command output substitution syntax.
Stores are implemented internally through Unix-domain sockets,
a writer program, <em>sgsh-writeval</em>(1), and a reader program, <em>sgsh-readval</em>(1).
The behavior of store I/O can be modified by adding
<em>sgsh-writeval</em>(1) and <em>sgsh-readval</em>(1) flags after the store's name.
In particular, flags can be used to operate on windows of stream data,
rather than a single value written to a store.
</dd>
<dt>Streams</dt><dd> are named as <code>/stream/</code><em>name</em>.
In addition, unnamed streams can be specified with a single dash when
writing to a data sink (<code>|-</code>),
and with <code><-</code> when reading from it.
Unnamed streams read match lexically the sequence of unnamed streams written.
(The first specified unnamed output stream will be read by
the first specified unnamed input stream.)
Streams connect the output of one process
with the input of another.
In contrast to scatter blocks,
which restrict the data flow through a tree of processes,
streams allow the specification of a directed acyclic process graph.
Streams require exactly one reader and one writer,
operating asynchronously, in order to operate.
Consequently, they should not be used in sequential synchronous steps
specified in the gather block, because steps waiting to be executed
will completely block all upstream processing in the scatter block.
Streams are internally implemented through named pipes.
</dd>
</dl>
</section>
<section id="syntax"> <!-- {{{2 -->
<h2>Syntax</h2>
<p>
An <em>sgsh</em> script follows the syntax of an <em>sh</em>(1) shell
script with the addition of <em>scatter/gather</em> blocks.
A <em>scatter</em> block starts with a line
containing the sequence <code>scatter |{</code>.
Data may be redirected or piped into and out of the block.
A scatter block contains one or more <em>sgsh</em> commands,
which are executed asynchronously (in parallel, in the background).
Each command starts with a source (input) specification at
the beginning of a line:
<code>-|</code> to receive input that was piped into the
scatter block, or
<code>.|</code> to specify that no input will be received.
Then follows a normal <em>sh</em>(1) pipeline,
followed by a sink (output) specification at the end of a line.
This can be a stream (<code>|>/stream/</code><em>name</em> or <code>|-</code>),
a data store (<code>|store:</code><em>name</em>),
<code>|.</code> to specify that no output will be generated,
or a nested scatter block
(starting with <code>|{</code> and ending with <code>|}</code>).
</p>
<p>
The (optional) <em>gather</em> block starts with a line
containing the sequence <code>|} gather |{</code>,
which also ends the preceding scatter block,
and ends with a line containing <code>|}</code>.
The gather block contains normal <em>sh</em>(1) commands,
which are executed synchronously&emdash;one by one in the specified order.
Names of data stores and streams appearing in the gather
block are set to match the output of the corresponding gather commands.
The gather block ends with <code>|}</code> appearing in a single line.
The <code>|}</code> token terminating the gather block can be followed
by redirection operators,
like <code>|</code>, <code><</code>, and <code>></code>.
</p>
<p>
In the following example the output of <em>ls</em> is scattered to
three commands:
<em>grep</em>, which counts the number of directories and stores the
result into the <code>NDIRS</code> store,
<em>awk</em>, which sums the number of bytes and stores the
result into the <code>NBYTES</code> store, and
an empty command,
which simply sends a copy of its input to the <code>files</code> stream.
The commands in the <em>gather</em> block retrieve and display the
data from the stores and the stream.
</p>
<pre class="prettyprint lang-bash">
#!/usr/bin/env sgsh
ls -n |
scatter |{
# Count number of directories
-| grep -c '^d' |store:NDIRS
# Tally number of bytes
-| awk '{s += $5} END {print s}' |store:NBYTES
# Copy of the files
-||>/stream/files
|} gather |{
cat /stream/files
echo "`store:NDIRS` Dir(s) `store:NBYTES` bytes"
|}
</pre>
<p>
Here the formal description of the <em>sgsh</em> syntax.
</p>
<pre class="prettyprint">
<!-- #!sh format-syntax.sh -->
</pre>
</section> <!-- syntax -->
<!-- Downloading and installation {{{1
================================================== -->
<section id="download">
<div class="page-header">
<h1>Downloading and installation</h1>
</div>
<p>
You can clone the project's source code through its
<a href="https://github.com/dspinellis/sgsh">GitHub page</a>.
Alternatively, you can download the latest version of the source code
as a zip file through
<a href="https://github.com/dspinellis/sgsh/archive/master.zip">this link</a>.
</p>
<p>
To compile and run <em>sgsh</em> you will need to have
a C compiler, GNU make, and <a href="http://www.perl.org/">Perl</a>
installed in your system.
The optional Perl module <em>Graph</em> is used to detect cycles that
can lead to deadlocks.
An installation of <a href="http://www.graphviz.org/">GraphViz</a>
will allow you to visualize the <em>sgsh</em> graphs that you specify
in your programs.
The <em>sgsh</em> suite has been tested under
Cygwin, Debian Linux, FreeBSD, and Mac OS X.
</p>
<p>
To install the <em>sgsh</em> suite run <code>make</code>,
followed by <code>sudo make install</code>.
By default, the program and its documentation are installed under
<code>/usr/local</code>.
You can modify this by setting the <code>INSTPREFIX</code> variable
during installation,
e.g. <code>sudo make INSTPREFIX=/usr install</code>.
Alternatively, you can also run <em>sgsh</em> from its current
directory, by running <code>make</code> and then using the <code>-p</code>
flag to specify the location of the helper programs,
as in
<code>./sgsh -p . example/compress-compare.sh http://www.google.com</code>.
</p>
</section>
<!-- Debugging and profiling {{{1
================================================== -->
<section id="debug">
<div class="page-header">
<h1>Debugging and profiling</h1>
</div>
<p>
Running <em>sgsh</em> with the <code>-d</code> option will
generate and launch a web-based debug and monitoring interface.
This amounts to
generating a graph of the running processes,
instrumenting the code with monitoring probes,
running a tiny web server to respond to AJAX requests,
and opening a JavaScript-based web page depicting the processing graph.
</p>
<p>
Hovering the mouse over a graph's edge,
opens up another window displaying
the number of bytes and lines that have gone through the edge,
the edge's throughput in terms of bytes and lines per second,
the time the edge has been idle,
and (part) of the last record that have gone through the edge.
</p>
<img src="debug.png" class="img-polaroid" alt="Debugging interface" />
<p>
Hovering the mouse over a graph's processing node opens a popup window that
displays details about the top two processes running on that node
that impose the highest CPU load on the system.
</p>
<img src="profile.png" class="img-polaroid" alt="Profiling interface" />
<p>
The details listed vary according to the underlying operating system.
They include
elapsed, user, and system time,
resident set size, virtual set size,
processor number,
memory and CPU percentage claimed by the process, and
major and minor page faults.
</p>
</section> <!-- debug -->
<!-- Reference {{{1
================================================== -->
<section id="reference">
<div class="page-header">
<h1>Reference documentation</h1>
</div>
<p>
These are the manual pages for <em>sgsh</em> and the associated helper programs
in formats suitable for browsing and printing.
</p>
<dl >
<dt> sgsh </dt><dd> scatter gather shell <a href="sgsh.html">HTML</a>, <a href="sgsh.pdf">PDF</a></dd>
<dt> sgsh-tee </dt><dd> buffer and copy or scatter standard input to one or more sinks <a href="sgsh-tee.html">HTML</a>, <a href="sgsh-tee.pdf">PDF</a></dd>
<dt> sgsh-writeval </dt><dd> write values to a data store <a href="sgsh-writeval.html">HTML</a>, <a href="sgsh-writeval.pdf">PDF</a></dd>
<dt> sgsh-readval </dt><dd> data store client <a href="sgsh-readval.html">HTML</a>, <a href="sgsh-readval.pdf">PDF</a></dd>
<dt> sgsh-httpval </dt><dd> data store HTTP server <a href="sgsh-httpval.html">HTML</a>, <a href="sgsh-httpval.pdf">PDF</a></dd>
<dt> sgsh-monitor </dt><dd> pipe monitoring filter <a href="sgsh-monitor.html">HTML</a>, <a href="sgsh-monitor.pdf">PDF</a></dd>
<dt> sgsh-ps </dt><dd> process status provider <a href="sgsh-ps.html">HTML</a>, <a href="sgsh-ps.pdf">PDF</a></dd>
</dl>
</section>
<!-- Examples {{{1
================================================== -->
<section id="examples">
<div class="page-header">
<h1>Examples</h1>
</div>
<!-- #!sh format-eg.sh -->
</section> <!-- Examples -->
</div> <!-- span8 -->
</div> <!-- row -->
<!-- Bootstrap -->
<script src="http://code.jquery.com/jquery.js"></script>
<script src="../../a/bootstrap/js/bootstrap.min.js"></script>
<script type="text/javascript" src="../../a/prettify/prettify.js"></script>
<script>
$(document).ready(function() {
prettyPrint();
});
</script>
<div class="license">
<!--Creative Commons License--><a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/gr/deed.en">
<img alt="Creative Commons License" src="http://creativecommons.org/images/public/somerights20.png"/></a>
Unless otherwise expressly stated, all original material on this page
created by Diomidis Spinellis is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/gr/deed.en">Creative Commons Attribution-Share Alike 3.0 Greece License</a>.
</div>
</body>
</html>