← Back to branch summary

~akopytov/percona-xtrabackup/bug1166888-2.1

« back to all changes in this revision

Viewing changes to src/libarchive/libarchive/libarchive_internals.3

  • Committer: Alexey Kopytov
  • Date: 2012-02-10 20:05:56 UTC
  • mto: (391.1.5 staging)
  • mto: This revision was merged to the branch mainline in revision 390.
  • Revision ID: akopytov@gmail.com-20120210200556-6kx41z8wwrqfucro
Rebase of the parallel compression patch on new trunk + post-review
fixes.

Implementation of parallel compression and streaming for XtraBackup.

This revision implements the following changes:

* InnoDB files are now streamed by the xtrabackup binary rather than
innobackupex. As a result, integrity is now verified by xtrabackup and
thus tar4ibd is no longer needed, so it was removed.

* xtrabackup binary now accepts the new '--stream' option which has
exactly the same semantics as the '--stream' option in
innobackupex: it tells xtrabackup to stream all files to the standard
output in the specified format rather than storing them locally.

* The xtrabackup binary can now do parallel compression using the
quicklz library. Two new options were added to xtrabackup to support
this feature:

- '--compress' tells xtrabackup to compress all output data, including
the transaction log file and meta data files, using the specified
compression algorithm. The only currently supported algorithm is
'quicklz'. The resulting files have the qpress archive format,
i.e. every *.qp file produced by xtrabackup is essentially a one-file
qpress archive and can be extracted and uncompressed by the qpress
file archiver (http://www.quicklz.com/).

- '--compress-threads' specifies the number of worker threads used by
xtrabackup for parallel data compression. This option defaults to 1.

Parallel compression ('--compress-threads') can be used together with
parallel file copying ('--parallel'). For example, '--parallel=4
--compress --compress-threads=2' will create 4 IO threads that will
read the data and pipe it to 2 compression threads.

* To support simultaneous compression and streaming, a new custom
streaming format called 'xbstream' was introduced to XtraBackup in
addition to the 'tar' format. That was required to overcome some
limitations of traditional archive formats such as 'tar', 'cpio' and
others that do not allow streaming dynamically generated files, for
example dynamically compressed files.  Other advantages of xbstream over
traditional streaming/archive formats include ability to stream multiple
files concurrently (so it is possible to use streaming in the xbstream
format together with the --parallel option) and more compact data
storage.

* To allow streaming and extracting files to/from the xbstream format
produced by xtrabackup, a new utility aptly called 'xbstream' was
added to the XtraBackup distribution. This utility has a tar-like
interface:

- with the '-x' option it extracts files from the stream read from its
standard input to the current directory unless specified otherwise
with the '-C' option.

- with the '-c' option it streams files specified on the command line
to its standard output.

The utility also tries to minimize its impact on the OS page cache by
using the appropriate posix_fadvise() calls when available.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/libarchive/libarchive/libarchive_internals.3
 
1
.\" Copyright (c) 2003-2007 Tim Kientzle
 
2
.\" All rights reserved.
 
3
.\"
 
4
.\" Redistribution and use in source and binary forms, with or without
 
5
.\" modification, are permitted provided that the following conditions
 
6
.\" are met:
 
7
.\" 1. Redistributions of source code must retain the above copyright
 
8
.\"    notice, this list of conditions and the following disclaimer.
 
9
.\" 2. Redistributions in binary form must reproduce the above copyright
 
10
.\"    notice, this list of conditions and the following disclaimer in the
 
11
.\"    documentation and/or other materials provided with the distribution.
 
12
.\"
 
13
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 
14
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 
15
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 
16
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 
17
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 
18
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 
19
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 
20
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 
21
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 
22
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 
23
.\" SUCH DAMAGE.
 
24
.\"
 
25
.\" $FreeBSD: src/lib/libarchive/libarchive_internals.3,v 1.2 2007/12/30 04:58:22 kientzle Exp $
 
26
.\"
 
27
.Dd April 16, 2007
 
28
.Dt LIBARCHIVE 3
 
29
.Os
 
30
.Sh NAME
 
31
.Nm libarchive_internals
 
32
.Nd description of libarchive internal interfaces
 
33
.Sh OVERVIEW
 
34
The
 
35
.Nm libarchive
 
36
library provides a flexible interface for reading and writing
 
37
streaming archive files such as tar and cpio.
 
38
Internally, it follows a modular layered design that should
 
39
make it easy to add new archive and compression formats.
 
40
.Sh GENERAL ARCHITECTURE
 
41
Externally, libarchive exposes most operations through an
 
42
opaque, object-style interface.
 
43
The
 
44
.Xr archive_entry 1
 
45
objects store information about a single filesystem object.
 
46
The rest of the library provides facilities to write
 
47
.Xr archive_entry 1
 
48
objects to archive files,
 
49
read them from archive files,
 
50
and write them to disk.
 
51
(There are plans to add a facility to read
 
52
.Xr archive_entry 1
 
53
objects from disk as well.)
 
54
.Pp
 
55
The read and write APIs each have four layers: a public API
 
56
layer, a format layer that understands the archive file format,
 
57
a compression layer, and an I/O layer.
 
58
The I/O layer is completely exposed to clients who can replace
 
59
it entirely with their own functions.
 
60
.Pp
 
61
In order to provide as much consistency as possible for clients,
 
62
some public functions are virtualized.
 
63
Eventually, it should be possible for clients to open
 
64
an archive or disk writer, and then use a single set of
 
65
code to select and write entries, regardless of the target.
 
66
.Sh READ ARCHITECTURE
 
67
From the outside, clients use the
 
68
.Xr archive_read 3
 
69
API to manipulate an
 
70
.Nm archive
 
71
object to read entries and bodies from an archive stream.
 
72
Internally, the
 
73
.Nm archive
 
74
object is cast to an
 
75
.Nm archive_read
 
76
object, which holds all read-specific data.
 
77
The API has four layers:
 
78
The lowest layer is the I/O layer.
 
79
This layer can be overridden by clients, but most clients use
 
80
the packaged I/O callbacks provided, for example, by
 
81
.Xr archive_read_open_memory 3 ,
 
82
and
 
83
.Xr archive_read_open_fd 3 .
 
84
The compression layer calls the I/O layer to
 
85
read bytes and decompresses them for the format layer.
 
86
The format layer unpacks a stream of uncompressed bytes and
 
87
creates
 
88
.Nm archive_entry
 
89
objects from the incoming data.
 
90
The API layer tracks overall state
 
91
(for example, it prevents clients from reading data before reading a header)
 
92
and invokes the format and compression layer operations
 
93
through registered function pointers.
 
94
In particular, the API layer drives the format-detection process:
 
95
When opening the archive, it reads an initial block of data
 
96
and offers it to each registered compression handler.
 
97
The one with the highest bid is initialized with the first block.
 
98
Similarly, the format handlers are polled to see which handler
 
99
is the best for each archive.
 
100
(Prior to 2.4.0, the format bidders were invoked for each
 
101
entry, but this design hindered error recovery.)
 
102
.Ss I/O Layer and Client Callbacks
 
103
The read API goes to some lengths to be nice to clients.
 
104
As a result, there are few restrictions on the behavior of
 
105
the client callbacks.
 
106
.Pp
 
107
The client read callback is expected to provide a block
 
108
of data on each call.
 
109
A zero-length return does indicate end of file, but otherwise
 
110
blocks may be as small as one byte or as large as the entire file.
 
111
In particular, blocks may be of different sizes.
 
112
.Pp
 
113
The client skip callback returns the number of bytes actually
 
114
skipped, which may be much smaller than the skip requested.
 
115
The only requirement is that the skip not be larger.
 
116
In particular, clients are allowed to return zero for any
 
117
skip that they don't want to handle.
 
118
The skip callback must never be invoked with a negative value.
 
119
.Pp
 
120
Keep in mind that not all clients are reading from disk:
 
121
clients reading from networks may provide different-sized
 
122
blocks on every request and cannot skip at all;
 
123
advanced clients may use
 
124
.Xr mmap 2
 
125
to read the entire file into memory at once and return the
 
126
entire file to libarchive as a single block;
 
127
other clients may begin asynchronous I/O operations for the
 
128
next block on each request.
 
129
.Ss Decompresssion Layer
 
130
The decompression layer not only handles decompression,
 
131
it also buffers data so that the format handlers see a
 
132
much nicer I/O model.
 
133
The decompression API is a two stage peek/consume model.
 
134
A read_ahead request specifies a minimum read amount;
 
135
the decompression layer must provide a pointer to at least
 
136
that much data.
 
137
If more data is immediately available, it should return more:
 
138
the format layer handles bulk data reads by asking for a minimum
 
139
of one byte and then copying as much data as is available.
 
140
.Pp
 
141
A subsequent call to the
 
142
.Fn consume
 
143
function advances the read pointer.
 
144
Note that data returned from a
 
145
.Fn read_ahead
 
146
call is guaranteed to remain in place until
 
147
the next call to
 
148
.Fn read_ahead .
 
149
Intervening calls to
 
150
.Fn consume
 
151
should not cause the data to move.
 
152
.Pp
 
153
Skip requests must always be handled exactly.
 
154
Decompression handlers that cannot seek forward should
 
155
not register a skip handler;
 
156
the API layer fills in a generic skip handler that reads and discards data.
 
157
.Pp
 
158
A decompression handler has a specific lifecycle:
 
159
.Bl -tag -compact -width indent
 
160
.It Registration/Configuration
 
161
When the client invokes the public support function,
 
162
the decompression handler invokes the internal
 
163
.Fn __archive_read_register_compression
 
164
function to provide bid and initialization functions.
 
165
This function returns
 
166
.Cm NULL
 
167
on error or else a pointer to a
 
168
.Cm struct decompressor_t .
 
169
This structure contains a
 
170
.Va void * config
 
171
slot that can be used for storing any customization information.
 
172
.It Bid
 
173
The bid function is invoked with a pointer and size of a block of data.
 
174
The decompressor can access its config data
 
175
through the
 
176
.Va decompressor
 
177
element of the
 
178
.Cm archive_read
 
179
object.
 
180
The bid function is otherwise stateless.
 
181
In particular, it must not perform any I/O operations.
 
182
.Pp
 
183
The value returned by the bid function indicates its suitability
 
184
for handling this data stream.
 
185
A bid of zero will ensure that this decompressor is never invoked.
 
186
Return zero if magic number checks fail.
 
187
Otherwise, your initial implementation should return the number of bits
 
188
actually checked.
 
189
For example, if you verify two full bytes and three bits of another
 
190
byte, bid 19.
 
191
Note that the initial block may be very short;
 
192
be careful to only inspect the data you are given.
 
193
(The current decompressors require two bytes for correct bidding.)
 
194
.It Initialize
 
195
The winning bidder will have its init function called.
 
196
This function should initialize the remaining slots of the
 
197
.Va struct decompressor_t
 
198
object pointed to by the
 
199
.Va decompressor
 
200
element of the
 
201
.Va archive_read
 
202
object.
 
203
In particular, it should allocate any working data it needs
 
204
in the
 
205
.Va data
 
206
slot of that structure.
 
207
The init function is called with the block of data that
 
208
was used for tasting.
 
209
At this point, the decompressor is responsible for all I/O
 
210
requests to the client callbacks.
 
211
The decompressor is free to read more data as and when
 
212
necessary.
 
213
.It Satisfy I/O requests
 
214
The format handler will invoke the
 
215
.Va read_ahead ,
 
216
.Va consume ,
 
217
and
 
218
.Va skip
 
219
functions as needed.
 
220
.It Finish
 
221
The finish method is called only once when the archive is closed.
 
222
It should release anything stored in the
 
223
.Va data
 
224
and
 
225
.Va config
 
226
slots of the
 
227
.Va decompressor
 
228
object.
 
229
It should not invoke the client close callback.
 
230
.El
 
231
.Ss Format Layer
 
232
The read formats have a similar lifecycle to the decompression handlers:
 
233
.Bl -tag -compact -width indent
 
234
.It Registration
 
235
Allocate your private data and initialize your pointers.
 
236
.It Bid
 
237
Formats bid by invoking the
 
238
.Fn read_ahead
 
239
decompression method but not calling the
 
240
.Fn consume
 
241
method.
 
242
This allows each bidder to look ahead in the input stream.
 
243
Bidders should not look further ahead than necessary, as long
 
244
look aheads put pressure on the decompression layer to buffer
 
245
lots of data.
 
246
Most formats only require a few hundred bytes of look ahead;
 
247
look aheads of a few kilobytes are reasonable.
 
248
(The ISO9660 reader sometimes looks ahead by 48k, which
 
249
should be considered an upper limit.)
 
250
.It Read header
 
251
The header read is usually the most complex part of any format.
 
252
There are a few strategies worth mentioning:
 
253
For formats such as tar or cpio, reading and parsing the header is
 
254
straightforward since headers alternate with data.
 
255
For formats that store all header data at the beginning of the file,
 
256
the first header read request may have to read all headers into
 
257
memory and store that data, sorted by the location of the file
 
258
data.
 
259
Subsequent header read requests will skip forward to the
 
260
beginning of the file data and return the corresponding header.
 
261
.It Read Data
 
262
The read data interface supports sparse files; this requires that
 
263
each call return a block of data specifying the file offset and
 
264
size.
 
265
This may require you to carefully track the location so that you
 
266
can return accurate file offsets for each read.
 
267
Remember that the decompressor will return as much data as it has.
 
268
Generally, you will want to request one byte,
 
269
examine the return value to see how much data is available, and
 
270
possibly trim that to the amount you can use.
 
271
You should invoke consume for each block just before you return it.
 
272
.It Skip All Data
 
273
The skip data call should skip over all file data and trailing padding.
 
274
This is called automatically by the API layer just before each
 
275
header read.
 
276
It is also called in response to the client calling the public
 
277
.Fn data_skip
 
278
function.
 
279
.It Cleanup
 
280
On cleanup, the format should release all of its allocated memory.
 
281
.El
 
282
.Ss API Layer
 
283
XXX to do XXX
 
284
.Sh WRITE ARCHITECTURE
 
285
The write API has a similar set of four layers:
 
286
an API layer, a format layer, a compression layer, and an I/O layer.
 
287
The registration here is much simpler because only
 
288
one format and one compression can be registered at a time.
 
289
.Ss I/O Layer and Client Callbacks
 
290
XXX To be written XXX
 
291
.Ss Compression Layer
 
292
XXX To be written XXX
 
293
.Ss Format Layer
 
294
XXX To be written XXX
 
295
.Ss API Layer
 
296
XXX To be written XXX
 
297
.Sh WRITE_DISK ARCHITECTURE
 
298
The write_disk API is intended to look just like the write API
 
299
to clients.
 
300
Since it does not handle multiple formats or compression, it
 
301
is not layered internally.
 
302
.Sh GENERAL SERVICES
 
303
The
 
304
.Nm archive_read ,
 
305
.Nm archive_write ,
 
306
and
 
307
.Nm archive_write_disk
 
308
objects all contain an initial
 
309
.Nm archive
 
310
object which provides common support for a set of standard services.
 
311
(Recall that ANSI/ISO C90 guarantees that you can cast freely between
 
312
a pointer to a structure and a pointer to the first element of that
 
313
structure.)
 
314
The
 
315
.Nm archive
 
316
object has a magic value that indicates which API this object
 
317
is associated with,
 
318
slots for storing error information,
 
319
and function pointers for virtualized API functions.
 
320
.Sh MISCELLANEOUS NOTES
 
321
Connecting existing archiving libraries into libarchive is generally
 
322
quite difficult.
 
323
In particular, many existing libraries strongly assume that you
 
324
are reading from a file; they seek forwards and backwards as necessary
 
325
to locate various pieces of information.
 
326
In contrast, libarchive never seeks backwards in its input, which
 
327
sometimes requires very different approaches.
 
328
.Pp
 
329
For example, libarchive's ISO9660 support operates very differently
 
330
from most ISO9660 readers.
 
331
The libarchive support utilizes a work-queue design that
 
332
keeps a list of known entries sorted by their location in the input.
 
333
Whenever libarchive's ISO9660 implementation is asked for the next
 
334
header, checks this list to find the next item on the disk.
 
335
Directories are parsed when they are encountered and new
 
336
items are added to the list.
 
337
This design relies heavily on the ISO9660 image being optimized so that
 
338
directories always occur earlier on the disk than the files they
 
339
describe.
 
340
.Pp
 
341
Depending on the specific format, such approaches may not be possible.
 
342
The ZIP format specification, for example, allows archivers to store
 
343
key information only at the end of the file.
 
344
In theory, it is possible to create ZIP archives that cannot
 
345
be read without seeking.
 
346
Fortunately, such archives are very rare, and libarchive can read
 
347
most ZIP archives, though it cannot always extract as much information
 
348
as a dedicated ZIP program.
 
349
.Sh SEE ALSO
 
350
.Xr archive 3 ,
 
351
.Xr archive_entry 3 ,
 
352
.Xr archive_read 3 ,
 
353
.Xr archive_write 3 ,
 
354
.Xr archive_write_disk 3
 
355
.Sh HISTORY
 
356
The
 
357
.Nm libarchive
 
358
library first appeared in
 
359
.Fx 5.3 .
 
360
.Sh AUTHORS
 
361
.An -nosplit
 
362
The
 
363
.Nm libarchive
 
364
library was written by
 
365
.An Tim Kientzle Aq kientzle@acm.org .