[105ccd]: doxymain.h  Maximize  Restore  History

Download this file

668 lines (645 with data), 32.5 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
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
/*! \mainpage Documentation for STXXL library
*
* \image html logo1.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
*
*
* \section platforms Supported Operating Systems
* - Linux (kernel >= 2.4.18)
* - Solaris
* - Mac OS X
* - other POSIX compatible systems should work, but have not been tested
* - Windows 2000/XP/Vista
*
*
* \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.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 10.1.017 | x�� MCSTL�� x�� MCSTL��
ICPC 10.0.026 | x�� MCSTL�� x�� MCSTL��
ICPC 9.1.053 | x�� - x�� -
ICPC 9.0.032 | x�� - x�� -
MSVC 2008 9.0 | - - x -
MSVC 2005 8.0 | - - x -
x = full support
o = partial support
- = unsupported
? = untested
MCSTL = supports parallelization using the MCSTL library
PMODE = supports parallelization using libstdc++ parallel mode
�� = 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 gcc 3.x
icpc 9.1: use gcc before 4.2
icpc 10.x with mcstl support: use gcc 4.2
�� = MCSTL has been superseded by the libstdc++ parallel mode in GCC 4.3,
requires g++ 4.3.2 (prerelease) 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.34.1.
* It also compiles using Boost 1.35.0 without problems,
* but hasn't been thoroughly tested in this setting.
* Other versions may work, too, but older versions won't get support.
*
*
* \section installation Installation and Usage Instructions
*
* - \link installation_linux_gcc Installation (Linux/g++) \endlink
* - \link installation_solaris_gcc Installation (Solaris/g++) \endlink
* - \link installation_msvc Installation (Windows/MS Visual C++ 8.0) \endlink
* - \link installation_old Installation of the older Stxxl versions (earlier than 0.9) (Linux/g++) \endlink
*
* - \link install-svn Installing from subversion \endlink
*
*
* \section questions Questions
*
* - Questions concerning use and development of the \c S<small>TXXL</small>
* library and bug reports should be posted to the
* <b><a href="http://sourceforge.net/forum/?group_id=131632">FORUMS</a></b>
* or mailed to <A href="http://i10www.ira.uka.de/dementiev/">Roman Dementiev</A>.
*
* - \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.uni-karlsruhe.de/dementiev/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 stxxl::vector with \c n pages and LRU replacement strategy it
* can be guaranteed that the last \c n references
* obtained using stxxl::vector operator [] or dereferencing
* an iterator are valid. <br>
*
*
* \section q2 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.
*
*/
/*!
* \page install Installation
* - \link installation_linux_gcc Installation (Linux/g++) \endlink
* - \link installation_solaris_gcc Installation (Solaris/g++) \endlink
* - \link installation_msvc Installation (Windows/MS Visual C++ 8.0) \endlink
* - \link installation_old Installation of the older Stxxl versions (earlier than 0.9) (Linux/g++) \endlink
*
* - \link install-svn Installing from subversion \endlink
*/
/*!
* \page installation_linux_gcc Installation (Linux/g++ - Stxxl from version 1.1)
*
* \section download Download and library compilation
*
* - Download the latest gzipped tarball from
* <A href="http://sourceforge.net/project/showfiles.php?group_id=131632&package_id=144407">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 ,
* - 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.
* - Change the \c make.settings.local file according to your system configuration:
* - \c S<small>TXXL</small> root directory \c STXXL_ROOT variable
* ( \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 \c USE_BOOST variable to \c yes
* - change \c BOOST_ROOT variable according to the Boost root path
* - if you want \c S<small>TXXL</small> to use the <A href="http://algo2.iti.uni-karlsruhe.de/singler/mcstl/">MCSTL</A>
* library (you should have the MCSTL library already installed)
* - change \c MCSTL_ROOT variable according 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 \c OPT variable to \c -O3 or other g++ optimization level you like (default: \c -O3 )
* - (optionally) set \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
* - Run: \verbatim make library_g++ \endverbatim
* - Run: \verbatim make tests_g++ \endverbatim (optional, if you want to compile and run some test programs)
*
*
* \section compile_apps Application compilation
*
* After compiling the library, some Makefile variables are written to
* \c stxxl.mk (\c mcstxxl.mk if you 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)
# 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) $(CPPFLAGS) $(CXXFLAGS) my_example.o -o $@ $(STXXL_LDLIBS)
\endverbatim
*
* 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 MB/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
*
* Our library take benefit of direct user memory - disk transfers (direct access) which avoids
* superfluous copies.
* We recommend to use the
* \c XFS file system (<A href="http://oss.sgi.com/projects/xfs/">link</A>) that
* gives good read and write performance for large files.
* Note that file creation speed of \c XFS is slow, so that disk
* files should be precreated.
*
* 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
*
*
* \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
* - \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 uses \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 : performs disks transfers using \c mmap and \c munmap system calls
* - \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
*
* See also the example configuration file \c 'config_example' included in the tarball.
*
*
* \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 (Windows/MS Visual C++ 8.0 - Stxxl from version 0.9)
*
* \section download Download and library compilation
*
* - 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/project/showfiles.php?group_id=131632&package_id=144407">SourceForge</A>.
* - Unpack the zip file in some directory (e.g. \c 'c:\\' ),
* - Change to \c stxxl directory: \c cd \c stxxl-x.y.z ,
* - Change \c make.settings.msvc file according to your system configuration:
* - \c S<small>TXXL</small> root directory \c STXXL_ROOT variable
* ( \c directory_where_you_unpacked_the_zipfile\\stxxl-x.y.z , e.g. \c 'c:\\stxxl' )
* - change \c BOOST_ROOT variable according to the Boost root path
* - (optionally) set \c OPT variable to \c /O2 or other VC++ optimization level you like
* - set \c DEBUG variable to \c /MDd for debug version of the \c Stxxl library
* or to \c /MD for the version without debugging information in object files
* - Open the \c stxxl.vcproj file (VS Solution Object) in Visual Studio .NET.
* 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 \c stxxl test programs by pressing Ctrl-Alt-F7
* (or choosing from 'Build' drop-down menu Rebuild Solution)
*
*
* \section compile_apps Application compilation
*
* 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 \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 MB/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: uses \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.
*
* 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 installation_solaris_gcc Installation (Solaris/g++ - Stxxl from version 1.1)
*
* \section download Download and library compilation
*
* - Download the latest gzipped tarball from
* <A href="http://sourceforge.net/project/showfiles.php?group_id=131632&package_id=144407">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 ,
* - Change \c make.settings.gnu or \c make.settings.local file according to your system configuration:
* - \c S<small>TXXL</small> root directory \c STXXL_ROOT variable
* ( \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 \c USE_BOOST variable to \c yes
* - change \c BOOST_ROOT variable according to the Boost root path
* - (optionally) set \c OPT variable to \c -O3 or other g++ optimization level you like (default: \c -O3 )
* - (optionally) set \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)
* - Run: \verbatim make library_g++ \endverbatim
* - Run: \verbatim make tests_g++ \endverbatim (optional, if you want to compile and run some test programs)
*
*
* \section compile_apps Application compilation
*
* After compiling the library, some Makefile variables are written to
* \c stxxl.mk (\c mcstxxl.mk if you 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)
# 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) $(CPPFLAGS) $(CXXFLAGS) my_example.o -o $@ $(STXXL_LDLIBS)
\endverbatim
*
* 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 MB/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 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
* - \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 uses \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 : performs disks transfers using \c mmap and \c munmap system calls
* - \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
*
* See also the example configuration file \c 'config_example' included in the tarball.
*
*
* \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_old Installation (Linux/g++ - Stxxl versions earlier than 0.9)
*
* \section download Download and library compilation
*
* - Download stxxl_0.77.tgz from
* <A href="http://sourceforge.net/project/showfiles.php?group_id=131632&package_id=144407&release_id=541515">SourceForge</A>.
* - Unpack in some directory executing: \c tar \c zfxv \c stxxl_0.77.tgz ,
* - Change to \c stxxl directory: \c cd \c stxxl ,
* - Change file \c compiler.make according to your system configuration
* - name of your make program
* - name of your compiler
* - \c S<small>TXXL</small> root directory ( \c directory_where_you_unpacked_the_tar_ball/stxxl )
* - Run: \verbatim make lib \endverbatim
* - Run: \verbatim make tests \endverbatim (optional, if you want to run some test programs)
*
* In your makefiles of programs that will use \c S<small>TXXL</small> you should include
* the file \c compiler.make
* file (add the line 'include ../compiler.make') because it contains a useful variable (STXXL_VARS)
* that includes all compiler definitions and library paths that you need to compile an
* \c S<small>TXXL</small> program.
*
* For example: <BR> \verbatim g++ my_example.cpp -o my_example -g $(STXXL_VARS) \endverbatim
*
* Before you try to run one of the \c S<small>TXXL</small> examples
* (or your \c S<small>TXXL</small> program) you must configure the disk
* space that will be used as external memory for the library. 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 MB/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
*
* Our library take benefit of direct user memory - disk transfers (direct access) which avoids
* superfluous copies. This method has some disadvantages when accessing files on \c ext2 partitions.
* Namely one requires one byte of internal memory per each accessed kilobyte of file space. For external
* memory applications with large inputs this could be not proper. Therefore we recommend to use the
* \c XFS file system <A href="http://oss.sgi.com/projects/xfs/">link</A> which does not have this overhead but
* gives the same read and write performance. Note that file creation speed of \c XFS is slow, so that disk
* files must be precreated.
*
*
* \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
* - \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 uses \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 : performs disks transfers using \c mmap and \c munmap system calls
* - \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
*
* See also the example configuration file \c 'config_example' included in the tarball.
*
*
* \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 install-svn Installing from subversion
*
* \section checkout Retrieving the source from subversion
*
* The \c S<small>TXXL</small> sourcecode 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's 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 Installation
*
* Now follow the regular installation and usage instructions,
* skipping over the tarball download and extraction parts.<br>
* For the \c STXXL_ROOT variable value choose something like
* \c \$(HOME)/path/to/stxxl-trunk
*
* - \link installation_linux_gcc Installation (Linux/g++) \endlink
* - \link installation_solaris_gcc Installation (Solaris/g++) \endlink
* - \link installation_msvc Installation (Windows/MS Visual C++ 8.0) \endlink
*
* \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.
*
* Change to stxxl directory:
* \verbatim cd ...path/to/stxxl-trunk \endverbatim
* Run
* \verbatim svn update \endverbatim
* Usually you don't have to reconfigure anything, so just rebuild:
* - \verbatim make library_g++ \endverbatim
* - \verbatim make tests_g++ \endverbatim (optional, if you want to compile and run some test programs)
* */

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

JavaScript is required for this form.





No, thanks