pd.if.org Git - liblfds/blob - liblfds/liblfds6.1.0/liblfds610/readme.txt

   1 introduction
   2 ============
   3 Welcome to liblfds, a portable, license-free, lock-free data structure library
   4 written in C.
   5
   6 supported platforms
   7 ===================
   8 Out-of-the-box ports are provided for;
   9
  10 Operating System  CPU            Toolchain Choices
  11 ================  =============  =================
  12 Windows 64-bit    x64            1. Microsoft Visual Studio
  13                                  2. Microsoft Windows SDK and GNUmake
  14
  15 Windows 32-bit    x64, x86       1. Microsoft Visual Studio
  16                                  2. Visual C++ Express Edition
  17                                  3. Microsoft Windows SDK and GNUmake
  18
  19 Windows Kernel    x64, x86       1. Windows Driver Kit
  20
  21 Linux 64-bit      x64            1. GCC and GNUmake
  22
  23 Linux 32-bit      x64, x86, ARM  1. GCC and GNUmake
  24
  25 For more information including version requirements, see the building guide (lfds).
  26
  27 data structures
  28 ===============
  29 This release of liblfds provides the following;
  30
  31     * Freelist
  32     * Queue
  33     * Ringbuffer (each element read by a single reader)
  34     * Singly-linked list (logical delete only)
  35     * Stack
  36
  37 These are all many-readers, many-writers.
  38
  39 liblfds on-line
  40 ===============
  41 On the liblfds home page, you will find the blog, a bugzilla, a forum, a
  42 mediawiki and the current and all historical releases.
  43
  44 The mediawiki contains comprehensive documentation for development, building,
  45 testing and porting.
  46
  47 http://www.liblfds.org
  48
  49 license
  50 =======
  51 There is no license.  You are free to use this code in any way.
  52
  53 using
  54 =====
  55 Once built, there is a single header file, /inc/liblfds.h, which you must include
  56 in your source code, and a single library file /bin/liblfds.*, where the suffix
  57 depends on your platform and your build choice (static or dynamic), to which,
  58 if statically built, you must link directly or, if dynamically built, you must
  59 arrange your system such that the library can be found by the loader at run-time.
  60
  61 testing
  62 =======
  63 The library comes with a command line test and benchmark program.  This program
  64 requires threads.  As such, it is only suitable for platforms  which can execute
  65 a command line binary and provide thread support.  Currently this means the test
  66 and benchmark program works for all platforms except the Windows Kernel.
  67
  68 For documentation, see the testing and benchmarking guide in the mediawiki.
  69
  70 porting
  71 =======
  72 Both the test program and liblfds provide an abstraction layer which acts to
  73 mask platform differences. Porting is the act of implementing on your platform
  74 the functions which make up the abstraction layers.  You do not need to port
  75 the test program to port liblfds, but obviously it is recommended, so you can
  76 test your port.
  77
  78 To support liblfds, your platform MUST support;
  79
  80     * atomic single-word* increment
  81     * atomic single-word compare-and-swap
  82     * atomic contiguous double-word compare-and-swap*
  83     * malloc and free
  84     * compiler directive for alignment of variables declared on the stack
  85     * compiler directives for compiler barriers and processor barriers
  86
  87 * A ''word'' here means a type equal in length to the platform pointer size.
  88 * This requirement excludes the Alpha, IA64, MIPS, PowerPC and SPARC platforms.
  89
  90 Also, your platform MAY support;
  91
  92     * compiler keyword for function inlining
  93
  94 To support the test programme, your platform MUST support;
  95
  96     * determining the number of logical cores
  97     * threads (starting and waiting on for completion)
  98
  99 For documentation, see the porting guide (lfds) in the mediawiki.
 100
 101 release history
 102 ===============
 103 release 1, 25th September 2009, svn revision 1574.
 104   - initial release
 105
 106 release 2, 5th October 2009, svn revision 1599.
 107   - added abstraction layer for Windows kernel
 108   - minor code tidyups/fixes
 109
 110 release 3, 25th October 2009, svn revision 1652.
 111   - added singly linked list (logical delete only)
 112   - minor code tidyups/fixes
 113
 114 release 4, 7th December 2009, svn revision 1716.
 115   - added ARM support
 116   - added benchmarking functionality to the test program
 117   - fixed a profound and pervasive pointer
 118     declaration bug; earlier releases of liblfds
 119     *should not be used*
 120
 121 release 5, 19th December 2009, svn revision 1738.
 122   - fixed subtle queue bug, which also affected ringbuffer
 123     and caused data re-ordering under high load
 124   - added benchmarks for freelist, ringbuffer and stack
 125
 126 release 6, 29th December 2009, svn revision 1746.
 127   - fixed two implementation errors, which reduced performance,
 128     spotted by Codeplug from "http://cboard.cprogramming.com".
 129
 130 release 6.0.0, 18th December 2012, svn revision 2537
 131   - introduction of namespaces, e.g. the "lfds600_" prefix
 132     code otherwise COMPLETELY AND WHOLLY UNCHANGED
 133     this release is a stepping-stone to 6.1.0
 134
 135 release 6.1.0, 31th December 2012, svn revision 2600
 136   - fixed all existing non-enhancement bugs
 137   - discovered some new bugs and fixed them too
 138   - a very few minor changes/enhancements
 139