github.com/bhojpur/cache@v0.0.4/pkg/memory/doc.go (about)

     1  // Copyright (c) 2018 Bhojpur Consulting Private Limited, India. All rights reserved.
     2  
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  package memory
    22  
    23  /*
    24  It implements a low-level key/value database storage engine. It supports fully
    25  serializable transactions, ACID semantics, and lock-free MVCC with multiple
    26  readers and a single writer. The Bhojpur Cache in-memory database storage engine
    27  can be used for projects that want a simple data store without the need to add
    28  large dependencies such as PostgreSQL or MySQL.
    29  
    30  The Bhojpur Cache in-memory database storage engine is a single-level, zero-copy,
    31  B+tree data store. It means that the storage engine is optimized for fast read
    32  access and does not require recovery in the event of a system crash. Transactions
    33  which have not finished committing will simply be rolled back in the event of a
    34  system crash.
    35  
    36  The design of Bhojpur Cache in-memory database storage is based on Howard Chu's
    37  LMDB database project.
    38  
    39  The Bhojpur Cache in-memory database storage currently works on the Windows, macOS,
    40  and Linux operating system.
    41  
    42  Basics
    43  
    44  There are only a few types in Bhojpur Cache in-memory database storage: DB,
    45  Bucket, Tx, and Cursor. The DB is a collection of Buckets and is represented
    46  by a single file on the disk. A bucket is a collection of unique keys that
    47  are associated with values.
    48  
    49  Transactions provide either read-only or read-write access to the database.
    50  Read-only transactions can retrieve key/value pairs and can use Cursors to
    51  iterate over the dataset sequentially. Read-write transactions can create and
    52  delete buckets and can insert and remove keys. Only one read-write transaction
    53  is allowed at a time.
    54  
    55  Caveats
    56  
    57  The Bhojpur Cache in-memory database storage engine uses a read-only,
    58  memory-mapped data file to ensure that applications cannot corrupt the database.
    59  However, this means that keys and values returned from Bhojpur Cache in-memory
    60  database storage engine cannot be changed. Writing to a read-only byte slice
    61  will cause the Go runtime engine to panic.
    62  
    63  Keys and Values retrieved from the in-memory database are only valid for the
    64  life of the transaction. When used outside the transaction, these byte slices
    65  can point to different data or can point to invalid memory which will cause a
    66  panic.
    67  
    68  */