port/port_example.h

   1 // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file. See the AUTHORS file for names of contributors.
   4 //
   5 // This file contains the specification, but not the implementations,
   6 // of the types/operations/etc. that should be defined by a platform
   7 // specific port_<platform>.h file.  Use this file as a reference for
   8 // how to port this package to a new platform.
   9
  10 #ifndef STORAGE_LEVELDB_PORT_PORT_EXAMPLE_H_
  11 #define STORAGE_LEVELDB_PORT_PORT_EXAMPLE_H_
  12
  13 namespace leveldb {
  14 namespace port {
  15
  16 // TODO(jorlow): Many of these belong more in the environment class rather than
  17 //               here. We should try moving them and see if it affects perf.
  18
  19 // The following boolean constant must be true on a little-endian machine
  20 // and false otherwise.
  21 static const bool kLittleEndian = true /* or some other expression */;
  22
  23 // ------------------ Threading -------------------
  24
  25 // A Mutex represents an exclusive lock.
  26 class Mutex {
  27  public:
  28   Mutex();
  29   ~Mutex();
  30
  31   // Lock the mutex.  Waits until other lockers have exited.
  32   // Will deadlock if the mutex is already locked by this thread.
  33   void Lock();
  34
  35   // Unlock the mutex.
  36   // REQUIRES: This mutex was locked by this thread.
  37   void Unlock();
  38
  39   // Optionally crash if this thread does not hold this mutex.
  40   // The implementation must be fast, especially if NDEBUG is
  41   // defined.  The implementation is allowed to skip all checks.
  42   void AssertHeld();
  43 };
  44
  45 class CondVar {
  46  public:
  47   explicit CondVar(Mutex* mu);
  48   ~CondVar();
  49
  50   // Atomically release *mu and block on this condition variable until
  51   // either a call to SignalAll(), or a call to Signal() that picks
  52   // this thread to wakeup.
  53   // REQUIRES: this thread holds *mu
  54   void Wait();
  55
  56   // If there are some threads waiting, wake up at least one of them.
  57   void Signal();
  58
  59   // Wake up all waiting threads.
  60   void SignallAll();
  61 };
  62
  63 // A type that holds a pointer that can be read or written atomically
  64 // (i.e., without word-tearing.)
  65 class AtomicPointer {
  66  private:
  67   intptr_t rep_;
  68  public:
  69   // Initialize to arbitrary value
  70   AtomicPointer();
  71
  72   // Initialize to hold v
  73   explicit AtomicPointer(void* v) : rep_(v) { }
  74
  75   // Read and return the stored pointer with the guarantee that no
  76   // later memory access (read or write) by this thread can be
  77   // reordered ahead of this read.
  78   void* Acquire_Load() const;
  79
  80   // Set v as the stored pointer with the guarantee that no earlier
  81   // memory access (read or write) by this thread can be reordered
  82   // after this store.
  83   void Release_Store(void* v);
  84
  85   // Read the stored pointer with no ordering guarantees.
  86   void* NoBarrier_Load() const;
  87
  88   // Set va as the stored pointer with no ordering guarantees.
  89   void NoBarrier_Store(void* v);
  90 };
  91
  92 // ------------------ Compression -------------------
  93
  94 // Store the snappy compression of "input[0,input_length-1]" in *output.
  95 // Returns false if snappy is not supported by this port.
  96 extern bool Snappy_Compress(const char* input, size_t input_length,
  97                             std::string* output);
  98
  99 // If input[0,input_length-1] looks like a valid snappy compressed
 100 // buffer, store the size of the uncompressed data in *result and
 101 // return true.  Else return false.
 102 extern bool Snappy_GetUncompressedLength(const char* input, size_t length,
 103                                          size_t* result);
 104
 105 // Attempt to snappy uncompress input[0,input_length-1] into *output.
 106 // Returns true if successful, false if the input is invalid lightweight
 107 // compressed data.
 108 //
 109 // REQUIRES: at least the first "n" bytes of output[] must be writable
 110 // where "n" is the result of a successful call to
 111 // Snappy_GetUncompressedLength.
 112 extern bool Snappy_Uncompress(const char* input_data, size_t input_length,
 113                               char* output);
 114
 115 // ------------------ Miscellaneous -------------------
 116
 117 // If heap profiling is not supported, returns false.
 118 // Else repeatedly calls (*func)(arg, data, n) and then returns true.
 119 // The concatenation of all "data[0,n-1]" fragments is the heap profile.
 120 extern bool GetHeapProfile(void (*func)(void*, const char*, int), void* arg);
 121
 122 }  // namespace port
 123 }  // namespace leveldb
 124
 125 #endif  // STORAGE_LEVELDB_PORT_PORT_EXAMPLE_H_