[461a73]: doxymain.h Maximize Restore History

Download this file

doxymain.h    611 lines (595 with data), 29.8 kB

  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
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
/*! \mainpage Documentation for STXXL library
*
* \image html layer_diagram.png
*
* <br><br>
* The core of \c S<small>TXXL</small> is an implementation of the C++
* standard template library STL for external memory (out-of-core)
* computations, i.e., \c S<small>TXXL</small> implements containers and algorithms
* that can process huge volumes of data that only fit on
* disks. While the compatibility to the STL supports
* ease of use and compatibility with existing applications,
* another design priority is high performance.
* Here is a selection of \c S<small>TXXL</small> performance features:
* - transparent support of multiple disks
* - variable block lengths
* - overlapping of I/O and computation
* - prevention of OS file buffering overhead
* - algorithm pipelining
* - utilization of multiple processor cores for internal computation
*
*
* \section platforms Supported Operating Systems
* - Linux (kernel >= 2.4.18)
* - Mac OS X
* - FreeBSD
* - other POSIX compatible systems should work, but have not been tested
* - Windows 2000/XP/Vista/7
*
*
* \section compilers Supported Compilers
*
* The following compilers have been tested in different
* \c S<small>TXXL</small> configurations.
* Other compilers might work, too, but we don't have the resources
* (systems, compilers or time) to test them.
* Feedback is welcome.
*
* The compilers marked with '*' are the developer's favorite choices
* and are most thoroughly tested.
*
* \verbatim
| parallel parallel
| stxxl stxxl stxxl stxxl
compiler | + boost + boost
----------------+----------------------------------------
GCC 4.6 c++0x | x PMODE x PMODE
GCC 4.6 | x PMODE x PMODE
GCC 4.5 c++0x | x PMODE x PMODE
GCC 4.5 | x PMODE x PMODE
* GCC 4.4 c++0x | x PMODE x PMODE
GCC 4.4 | x PMODE x PMODE
GCC 4.3 c++0x | x PMODE�� x PMODE��
GCC 4.3 | x PMODE�� x PMODE��
GCC 4.2 | x MCSTL x MCSTL
GCC 4.1 | x - x -
GCC 4.0 | x - x -
GCC 3.4 | x - x -
GCC 3.3 | o - o -
GCC 2.95 | - - - -
ICPC 12.0.191 | x�� PMODE���� x�� PMODE����
ICPC 12.0.191 | x�� MCSTL�� x�� MCSTL��
* ICPC 11.1.075 | x�� MCSTL�� x�� MCSTL��
ICPC 11.0.084 | x�� MCSTL�� x�� MCSTL��
ICPC 10.1.026 | x�� MCSTL�� x�� MCSTL��
ICPC 10.0.026 | x�� MCSTL�� x�� MCSTL��
ICPC 9.1.053 | x�� - x�� -
ICPC 9.0.032 | x�� - x�� -
clang++ 2.9 | x - x -
MSVC 2010 10.0| - - x -
* MSVC 2008 9.0 | - - x -
MSVC 2005 8.0 | - - x -
x = full support
o = partial support
- = unsupported
? = untested
PMODE = supports parallelization using libstdc++ parallel mode
MCSTL = supports parallelization using the MCSTL library (superseded by
PMODE, introduced in gcc 4.3)
�� = you may have to add a -gcc-name=<gcc-x.y> option if the system default
gcc does not come in the correct version:
icpc 9.0: use with gcc 3.x
icpc 9.1: use with gcc before 4.2
icpc 10.x, 11.x, 12.0 with mcstl support: use with gcc 4.2
icpc 12.0 with pmode support: use with gcc 4.3
�� = gcc 4.3 only provides partial support for the libstdc++ parallel mode,
full support requires gcc 4.4 or later
\endverbatim
*
*
* \section boost Supported BOOST versions
*
* The <a href="http://www.boost.org">Boost</a> libraries are required on
* Windows platforms using MSVC compiler and optional on other platforms.
*
* \c S<small>TXXL</small> has been tested with Boost 1.40.0, 1.42.0 and 1.46.1.
* Other versions may work, too, but older versions will not get support.
*
*
* \section installation Instructions on installation, usage, configuration
*
* - \link installation_linux_gcc Installation, usage, configuration (Linux/Unix &ndash; g++/icpc/clang++) \endlink
* - \link installation_msvc Installation, usage, configuration (Windows &ndash; Microsoft Visual C++) \endlink
*
* - \link install-svn Installing from subversion \endlink
*
*
* \section questions Questions
*
* - Questions concerning use and development of the \c S<small>TXXL</small>
* library should be posted to the
* <b><a href="http://sourceforge.net/projects/stxxl/forums">FORUMS</a></b>.
* Please search the forum before posting,
* your question may have been answered before.
*
* \section bugreports Bug Reports
*
* - Bugs should be reported in the
* <b><a href="https://stxxl.ae.cs.uni-frankfurt.de/bugs/">Bugzilla Bug Tracker</a></b>
*
* - \link FAQ FAQ - Frequently Asked Questions \endlink
*
*
* \section license License
*
* \c S<small>TXXL</small> is distributed under the Boost Software License, Version 1.0.<br>
* You can find a copy of the license in the accompanying file \c LICENSE_1_0.txt or online at
* <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>.
*/
/*!
* \page FAQ FAQ - Frequently Asked Questions
*
* \section FAQ-latest Latest version of this FAQ
* The most recent version of this FAQ can always be found
* <a href="http://algo2.iti.kit.edu/stxxl/trunk/FAQ.html">here</a>.
*
*
* \section q1 References to Elements in External Memory Data Structures
*
* You should not pass or store references to elements in an external memory
* data structure. When the reference is used, the block that contains the
* element may be no longer in internal memory.<br>
* Use/pass an iterator (reference) instead.<br>
* For an \c stxxl::vector with \c n pages and LRU replacement strategy, it
* can be guaranteed that the last \c n references
* obtained using \c stxxl::vector::operator[] or dereferencing
* an iterator are valid.
* However, if \c n is 1, even a single innocent-looking line like
* \verbatim std::cout << v[0] << " " << v[1000000] << std::endl; \endverbatim can lead to
* inconsistent results.
* <br>
*
*
* \section q2 Parameterizing STXXL Containers
*
* STXXL container types like stxxl::vector can be parameterized only with a value type that is a
* <a href="http://en.wikipedia.org/wiki/Plain_old_data_structures">POD</a>
* (i. e. no virtual functions, no user-defined copy assignment/destructor, etc.)
* and does not contain references (including pointers) to internal memory.
* Usually, "complex" data types do not satisfy this requirements.
*
* This is why stxxl::vector<std::vector<T> > and stxxl::vector<stxxl::vector<T> > are invalid.
* If appropriate, use std::vector<stxxl::vector<T> >, or emulate a two-dimensional array by
* doing index calculation.
*
*
* \section q3 Thread-Safety
*
* The I/O and block management layers are thread-safe (since release 1.1.1).
* The user layer data structures are not thread-safe.<br>
* I.e. you may access <b>different</b> \c S<small>TXXL</small> data structures from concurrent threads without problems,
* but you should not share a data structure between threads (without implementing proper locking yourself).<br>
* This is a design choice, having the data structures thread-safe would mean a significant performance loss.
*
*
* \section q4 I have configured several disks to use with STXXL. Why does STXXL fail complaining about the lack of space? According to my calclulations, the space on the disks should be sufficient.
*
* This may happen if the disks have different size. With the default parameters \c S<small>TXXL</small> containers use randomized block-to-disk allocation strategies
* that distribute data evenly between the disks but ignore the availability of free space on them.
*
*
* \section q5 STXXL in a Microsoft CLR Library
*
* From STXXL user Christian, posted in the <a href="https://sourceforge.net/projects/stxxl/forums/forum/446474/topic/3407329">forum</a>:
*
* Precondition: I use STXXL in a Microsoft CLR Library (a special DLL). That means that managed code and native code (e.g. STXXL) have to co-exist in your library.
*
* Symptom: Application crashes at process exit, when the DLL is unloaded.
*
* Cause: STXXL's singleton classes use the \c atexit() function to destruct themselves at process exit. The exit handling will cause the process to crash at exit (still unclear if it's a bug or a feature of the MS runtime).
*
* Solution:
*
* 1.) Compiled STXXL static library with \c STXXL_NON_DEFAULT_EXIT_HANDLER defined.
*
* 2.) For cleanup, \c stxxl::run_exit_handlers() has now to be called manually. To get this done automatically:
*
* Defined a CLI singleton class "Controller":
*
* \verbatim
public ref class Controller {
private:
static Controller^ instance = gcnew Controller;
Controller();
};
\endverbatim
*
* Registered my own cleanup function in Controller's constructor which will manage to call \c stxxl::run_exit_handlers():
*
* \verbatim
#pragma managed(push, off)
static int myexitfn()
{
stxxl::run_exit_handlers();
return 0;
}
#pragma managed(pop)
Controller::Controller()
{
onexit(myexitfn);
}
\endverbatim
*
*
* \section q6 How can I credit STXXL, and thus foster its development?
*
* - For all users:
* - Sign up at Ohloh and add yourself as an STXXL user / rate STXXL: http://www.ohloh.net/p/stxxl
* - Rate STXXL at heise Software-Verzeichnis (German): http://www.heise.de/software/download/stxxl/76072
* - Rate STXXL at SourceForge: https://sourceforge.net/projects/stxxl/
*
* - For scientific work: Cite the papers mentioned here: http://stxxl.sourceforge.net/
*
* - For industrial users: Tell us the name of your company, so we can use it as a reference.
*
*/
/*!
* \page install Instructions on Installation, usage, configuration
* - \link installation_linux_gcc Installation, usage, configuration (Linux/Unix &ndash; g++/icpc/clang++) \endlink
* - \link installation_msvc Installation, usage, configuration (Windows &ndash; Microsoft Visual C++) \endlink
*
* - \link install-svn Installing from subversion \endlink
*/
/*!
* \page installation_linux_gcc Installation, usage, configuration (Linux/Unix &ndash; g++/icpc/clang++)
*
* \section download_linux_gcc Download and Extraction
*
* - Download the latest gzipped tarball from
* <a href="http://sourceforge.net/projects/stxxl/files/stxxl/">SourceForge</a>
* - Unpack in some directory executing: \c tar \c zfxv \c stxxl-x.y.z.tgz
* - Change to \c stxxl directory: \c cd \c stxxl-x.y.z
*
* \section library_compilation_linux_gcc Library Compilation
*
* - Run: \verbatim make config_gnu \endverbatim to create a template \c make.settings.local file.
* Note: this will produce some warnings and abort with an error, which is intended.
* - (optionally) change the \c make.settings.local file according to your system configuration:
* - (optionally) set the \c STXXL_ROOT variable to \c S<small>TXXL</small> root directory
* ( \c directory_where_you_unpacked_the_tar_ball/stxxl-x.y.z )
* - if you want \c S<small>TXXL</small> to use <a href="http://www.boost.org">Boost</a> libraries
* (you should have the Boost libraries already installed)
* - change the \c USE_BOOST variable to \c yes
* - change the \c BOOST_ROOT variable to the Boost root path, unless Boost is installed in system default search paths.
* - if you want \c S<small>TXXL</small> to use the <a href="http://gcc.gnu.org/onlinedocs/libstdc++/manual/parallel_mode.html">libstdc++ parallel mode</a>
* - use GCC version 4.3 or later
* - use the targets \c library_g++_pmode and \c tests_g++_pmode instead of the ones listed below
* - if you want \c S<small>TXXL</small> to use the <a href="http://algo2.iti.kit.edu/singler/mcstl/">MCSTL</a>
* library (you should have the MCSTL library already installed)
* - change the \c MCSTL_ROOT variable to the MCSTL root path
* - use the targets \c library_g++_mcstl and \c tests_g++_mcstl instead of the ones listed below
* - (optionally) set the \c OPT variable to \c -O3 or other g++ optimization level you like (default: \c -O3 )
* - (optionally) set the \c DEBUG variable to \c -g or other g++ debugging option
* if you want to produce a debug version of the Stxxl library or Stxxl examples (default: not set)
* - for more variables to tune take a look at \c make.settings.gnu ,
* they are usually overridden by settings in \c make.settings.local,
* using \c CPPFLAGS and \c LDFLAGS, for example, you can add arbitrary compiler and linker options
* - Run: \verbatim make library_g++ \endverbatim
* - Run: \verbatim make tests_g++ \endverbatim (optional, if you want to compile and run some test programs)
*
*
* \section build_apps Building an Application
*
* After compiling the library, some Makefile variables are written to
* \c stxxl.mk (\c pmstxxl.mk if you have built with parallel mode, \c mcstxxl.mk if you have built with MCSTL) in your
* \c STXXL_ROOT directory. This file should be included from your
* application's Makefile.
*
* The following variables can be used:
* - \c STXXL_CXX - the compiler used to build the \c S<small>TXXL</small>
* library, it's recommended to use the same to build your applications
* - \c STXXL_CPPFLAGS - add these flags to the compile commands
* - \c STXXL_LDLIBS - add these libraries to the link commands
*
* An example Makefile for an application using \c S<small>TXXL</small>:
* \verbatim
STXXL_ROOT ?= .../stxxl
STXXL_CONFIG ?= stxxl.mk
include $(STXXL_ROOT)/$(STXXL_CONFIG)
# use the variables from stxxl.mk
CXX = $(STXXL_CXX)
CPPFLAGS += $(STXXL_CPPFLAGS)
LDLIBS += $(STXXL_LDLIBS)
# add your own optimization, warning, debug, ... flags
# (these are *not* set in stxxl.mk)
CPPFLAGS += -O3 -Wall -g -DFOO=BAR
# build your application
# (my_example.o is generated from my_example.cpp automatically)
my_example.bin: my_example.o
$(CXX) $(CXXFLAGS) $(CPPFLAGS) $(LDFLAGS) my_example.o -o $@ $(LDLIBS)
\endverbatim
*
* \section parallel Enabling parallel execution
*
* To enable (shared-memory-)parallel execution of internal computation (in fact, sorting and merging, and random shuffling),
* you have several options depending on the \ref compilers "compiler version" used:
* - Enable the g++ parallel mode specifically for STXXL,
* by defining \c STXXL_PARALLEL_MODE_EXPLICIT and enabling OpenMP (\c -DSTXXL_PARALLEL_MODE_EXPLICIT \c -fopenmp)
* during compilation and linkage of your program.
* Compiling the library binary with this flag enabled is not really necessary,
* since the most time-consuming operations are called by the generic routines and thus contained in the header files.
* - Enable the g++ parallel mode for your program globally,
* by defining \c _GLIBCXX_PARALLEL and enabling OpenMP (\c -D_GLIBCXX_PARALLEL \c -fopenmp).
* This has the implication that STL algorithms in your program will also be executed in parallel,
* which may have undesired side effects.
* These options are automatically used when you built STXXL using the \c *_pmode target,
* and your Makefile includes \c pmstxxl.mk.
* - Enable MCSTL in your program by setting the include path appropriately.
* This implies that STL algorithms in your program will also be executed in parallel,
* which may have undesired side effects.
* These options are automatically used when you built STXXL using the \c *_mcstl target,
* and your Makefile includes \c mcstxxl.mk.
*
* We recommend to try the first option at first.
*
* The number of threads to be used can be set by the environment variable OMP_NUM_THREADS or
* by calling omp_set_num_threads.
* Detailed tuning can be achieved as described
* <a href="http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt03ch18s04.html#parallel_mode.design.tuning">here</a>.
*
*
* \section space Disk space
*
* Before you try to run one of the \c S<small>TXXL</small> examples
* (or your own \c S<small>TXXL</small> program) you must configure the disk
* space that will be used as external memory for the library.
*
* To get best performance with \c S<small>TXXL</small> you should assign separate disks to it.
* These disks should be used by the library only.
* Since \c S<small>TXXL</small> is developed to exploit disk parallelism, the performance of your
* external memory application will increase if you use more than one disk.
* But from how many disks your application can benefit depends on how "I/O bound" it is.
* With modern disk bandwidths
* of about 50-75 MiB/s most of applications are I/O bound for one disk. This means that if you add another disk
* the running time will be halved. Adding more disks might also increase performance significantly.
*
*
* \section filesystem Recommended file system
*
* The library benefits from direct transfers from user memory to disk, which saves superfluous copies.
* We recommend to use the
* \c <a href="http://xfs.org">XFS</a> file system,
* which gives good read and write performance for large files.
* Note that file creation speed of \c XFS is a bit slower,
* so that disk files should be precreated for optimal performance.
*
* If the filesystems only use is to store one large \c S<small>TXXL</small> disk file,
* we also recommend to add the following options to the \c mkfs.xfs command to gain maximum performance:
* \verbatim -d agcount=1 -l size=512b \endverbatim
*
* The following filesystems have been reported not to support direct I/O: \c tmpfs , \c glusterfs .
* Since direct I/O is enabled by default, you may recompile \c S<small>TXXL</small>
* with \c STXXL_DIRECT_IO_OFF defined to access files on these file systems.
*
*
* \section configuration Disk configuration file
*
* You must define the disk configuration for an
* \c S<small>TXXL</small> program in a file named \c '.stxxl' that must reside
* in the same directory where you execute the program.
* You can change the default file name for the configuration
* file by setting the environment variable \c STXXLCFG .
*
* Each line of the configuration file describes a disk.
* A disk description uses the following format:<br>
* \c disk=full_disk_filename,capacity,access_method
*
* Description of the parameters:
* - \c full_disk_filename : full disk filename. In order to access disks S<small>TXXL</small> uses file
* access methods. Each disk is represented as a file. If you have a disk that is mounted in Unix
* to the path /mnt/disk0/, then the correct value for the \c full_disk_filename would be
* \c /mnt/disk0/some_file_name ,
* - \c capacity : maximum capacity of the disk in megabytes
* (0 means autogrow, file will be deleted afterwards)
* - \c access_method : \c S<small>TXXL</small> has a number of different
* file access implementations for POSIX systems, choose one of them:
* - \c syscall : use \c read and \c write system calls which perform disk transfers directly
* on user memory pages without superfluous copying (currently the fastest method)
* - \c mmap : \c use \c mmap and \c munmap system calls
* - \c boostfd : access the file using a Boost file descriptor
* - \c fileperblock_syscall, \c fileperblock_mmap, \c fileperblock_boostfd :
* same as above, but take a single file per block, using full_disk_filename as file name prefix.
* Usually provide worse performance than the standard variants,
* but release freed blocks to the file system immediately.
* - \c simdisk : simulates timings of the IBM IC35L080AVVA07 disk, full_disk_filename must point
* to a file on a RAM disk partition with sufficient space
* - \c memory : keeps all data in RAM, for quicker testing
* - \c wbtl : library-based write-combining (good for writing small blocks onto SSDs),
* based on \c syscall
*
* See also the example configuration file \c 'config_example' included in the tarball.
*
*
* \section logfiles Log files
*
* \c S<small>TXXL</small> produces two kinds of log files, a message and an error log.
* By setting the environment variables \c STXXLLOGFILE and \c STXXLERRLOGFILE, you can configure
* the location of these files.
* The default values are \c stxxl.log and \c stxxl.errlog, respectively.
*
*
* \section excreation Precreating external memory files
*
* In order to get the maximum performance one should precreate disk files described in the configuration file,
* before running \c S<small>TXXL</small> applications.
*
* The precreation utility is included in the set of \c S<small>TXXL</small>
* utilities ( \c utils/createdisks.bin ). Run this utility
* for each disk you have defined in the disk configuration file:
* \verbatim utils/createdisks.bin capacity full_disk_filename... \endverbatim
*
* */
/*!
* \page installation_msvc Installation, usage, configuration (Windows &ndash; Microsoft Visual C++)
*
* \section download_msvc Download and Extraction
*
* - Install the <a href="http://www.boost.org">Boost</a> libraries (required).
* - Download the latest \c Stxxl zip file from
* <a href="http://sourceforge.net/projects/stxxl/files/stxxl/">SourceForge</a>
* - Unpack the zip file in some directory (e.&nbsp;g. \c 'C:\\' )
* - Change to \c stxxl base directory: \c cd \c stxxl-x.y.z
*
* \section library_compilation_msvc Library Compilation
*
* - Create \c make.settings.local in the base directory according to your system configuration:
* - set \c BOOST_ROOT variable according to the Boost root path, e.&nbsp;g.
* BOOST_ROOT = "C:\Program Files (x86)\boost\boost_1_40_0"#
* - (optionally) set \c STXXL_ROOT variable to \c S<small>TXXL</small> root directory
* - (optionally) set \c OPT variable to \c /O2 or any other VC++ optimization level you like,
* add -D_SECURE_SCL=0 to switch off iterator checking, which improves performance
* - (optionally) set \c DEBUG_COMPILER=/MDd /Zi and DEBUG_LINKER=/DEBUG enable debugging
* - Open the \c stxxl.vcproj file (VS Solution Object) in Visual Studio.
* The file is located in the \c STXXL_ROOT directory
* Press F7 to build the library.
* The library file (libstxxl.lib) should appear in \c STXXL_ROOT\\lib directory
* Or build the library and the S<small>TXXL</small> test programs by pressing Ctrl-Alt-F7
* (or choosing from 'Build' drop-down menu Rebuild Solution)
* - (alternatively) Compile the library by executing \c nmake \c library_msvc
* and the tests by executing \c nmake \c tests_msvc,
* with all the appropriate environment set (e.&nbsp;g. by using the VS Command Shell)
*
*
* \section build_apps Building an application
*
* Programs using Stxxl can be compiled using options from \c compiler.options
* file (in the \c STXXL_ROOT directory). The linking options for the VC++
* linker you can find in \c linker.options file. In order to accomplish this
* do the following:
* - Open project property pages (menu Project->Properties)
* - Choose C/C++->Command Line page.
* - In the 'Additional Options' field insert the contents of the \c compiler.options file.
* Make sure that the Runtime libraries/debug options (/MDd or /MD or /MT or /MTd) of
* the \c Stxxl library (see above) do not conflict with the options of your project.
* Use the same options in the \c Stxxl and your project.
* - Choose Linker->Command Line page.
* - In the 'Additional Options' field insert the contents of the \c linker.options file.
*
* <br>
* If you use make files you can
* include the \c make.settings file in your make files and use \c STXXL_COMPILER_OPTIONS and
* \c STXXL_LINKER_OPTIONS variables, defined therein.
*
* For example: <br>
* \verbatim cl -c my_example.cpp $(STXXL_COMPILER_OPTIONS) \endverbatim <br>
* \verbatim link my_example.obj /out:my_example.exe $(STXXL_LINKER_OPTIONS) \endverbatim
*
* <br>
* The \c STXXL_ROOT\\test\\WinGUI directory contains an example MFC GUI project
* that uses \c Stxxl. In order to compile it open the WinGUI.vcproj file in
* Visual Studio .NET. Change if needed the Compiler and Linker Options of the project
* (see above).
*
* Before you try to run one of the \c S<small>TXXL</small> examples
* (or your own \c S<small>TXXL</small> program) you must configure the disk
* space that will be used as external memory for the library. For instructions how to do that,
* see the next section.
*
*
* \section space Disk space
*
* To get best performance with \c S<small>TXXL</small> you should assign separate disks to it.
* These disks should be used by the library only.
* Since \c S<small>TXXL</small> is developed to exploit disk parallelism, the performance of your
* external memory application will increase if you use more than one disk.
* But from how many disks your application can benefit depends on how "I/O bound" it is.
* With modern disk bandwidths
* of about 50-75 MiB/s most of applications are I/O bound for one disk. This means that if you add another disk
* the running time will be halved. Adding more disks might also increase performance significantly.
*
*
* \section configuration Disk configuration file
*
* You must define the disk configuration for an
* \c S<small>TXXL</small> program in a file named \c '.stxxl' that must reside
* in the same directory where you execute the program.
* You can change the default file name for the configuration
* file by setting the environment variable \c STXXLCFG .
*
* Each line of the configuration file describes a disk.
* A disk description uses the following format:<br>
* \c disk=full_disk_filename,capacity,access_method
*
* Description of the parameters:
* - \c full_disk_filename : full disk filename. In order to access disks S<small>TXXL</small> uses file
* access methods. Each disk is represented as a file. If you have a disk called \c e:
* then the correct value for the \c full_disk_filename would be
* \c e:\\some_file_name ,
* - \c capacity : maximum capacity of the disk in megabytes
* - \c access_method : \c S<small>TXXL</small> has a number of different
* file access implementations for WINDOWS, choose one of them:
* - \c syscall : use \c read and \c write POSIX system calls (slow)
* - \c wincall: performs disks transfers using \c ReadFile and \c WriteFile WinAPI calls
* This method supports direct I/O that avoids superfluous copying of data pages
* in the Windows kernel. This is the best (and default) method in Stxxl for Windows.
* - \c boostfd : access the file using a Boost file descriptor
* - \c fileperblock_syscall, \c fileperblock_wincall, \c fileperblock_boostfd :
* same as above, but take a single file per block, using full_disk_filename as file name prefix.
* Usually provide worse performance than the standard variants,
* but release freed blocks to the file system immediately.
* - \c memory : keeps all data in RAM, for quicker testing
* - \c wbtl : library-based write-combining (good for writing small blocks onto SSDs),
* based on \c syscall
*
* See also the example configuration file \c 'config_example_win' included in the archive.
*
*
* \section excreation Precreating external memory files
*
* In order to get the maximum performance one should precreate disk files described in the configuration file,
* before running \c S<small>TXXL</small> applications.
*
* The precreation utility is included in the set of \c S<small>TXXL</small>
* utilities ( \c utils\\createdisks.exe ). Run this utility
* for each disk you have defined in the disk configuration file:
* \verbatim utils\createdisks.exe capacity full_disk_filename... \endverbatim
*
* */
/*!
* \page install-svn Installing from subversion
*
* \section checkout Retrieving the source from subversion
*
* The \c S<small>TXXL</small> source code is available in a subversion repository on sourceforge.net.<br>
* To learn more about subversion and (command line and graphical) subversion clients
* visit <a href="http://subversion.tigris.org/">http://subversion.tigris.org/</a>.
*
* The main development line (in subversion called the "trunk") is located at
* \c https://stxxl.svn.sourceforge.net/svnroot/stxxl/trunk
* <br>Alternatively you might use a branch where a new feature is being developed.
* Branches have URLs like
* \c https://stxxl.svn.sourceforge.net/svnroot/stxxl/branches/foobar
*
* For the following example let us assume you want to download the latest trunk version
* using the command line client and store it in a directory called \c stxxl-trunk
* (which should not exist, yet).
* Otherwise replace URL and path to your needs.
*
* Run: \verbatim svn checkout https://stxxl.svn.sourceforge.net/svnroot/stxxl/trunk stxxl-trunk \endverbatim
* Change to stxxl directory: \verbatim cd stxxl-trunk \endverbatim
*
* \section svn_continue_installation Continue as Usual
*
* Now follow the regular installation and usage instructions,
* starting from "Library Compilation":
* - \ref library_compilation_linux_gcc "Linux/Unix &ndash; g++/icpc/clang++"
* - \ref library_compilation_msvc "Windows &ndash; Microsoft Visual C++"
*
* \section update Updating an existing subversion checkout
*
* Once you have checked out the source code you can easily update it to the latest version later on.
*
* In the S<small>TXXL</small> directory, run
* \verbatim svn update \endverbatim
* and rebuild.
* */