Documentation

Author: pmenon

src/include/index/art_index.h

@@ -32,32 +32,47 @@ class ArtIndex : public Index {
   // Forward declare iterator class for later
   class Iterator;
 
-  /// Insert the given key-value pair into the index
   bool InsertEntry(const storage::Tuple *key, ItemPointer *value) override;
 
-  /// Delete the given key-value pair from the index
   bool DeleteEntry(const storage::Tuple *key, ItemPointer *value) override;
 
-  /// Insert the given key-value pair into the index, but only if the predicate
-  /// returns false for every instance of the given key in the index
   bool CondInsertEntry(const storage::Tuple *key, ItemPointer *value,
                        std::function<bool(const void *)> predicate) override;
 
-  /// Scan the range of keys between [start,end] inclusive, placing results in
-  /// the provided result vector
+  /**
+   * Perform a range scan of keys between [start,end] inclusive.
+   *
+   * @param start The start key
+   * @param end The end key
+   * @param[out] result Where the results of the scan are stored
+   * @param scan_predicate
+   */
   void ScanRange(const storage::Tuple *start, const storage::Tuple *end,
                  std::vector<ItemPointer *> &result);
 
-  /// Perform a scan, using the predicate, and place the results into the
-  /// provided result vector
+  /**
+   * ArtIndex throws away the first three arguments and only uses the conjuncts
+   * from the scan predicate.
+   *
+   * @param scan_predicate The only predicate that's actually used.
+   * @param[out] result Where the results of the scan are stored
+   */
   void Scan(const std::vector<type::Value> &values,
             const std::vector<oid_t> &key_column_ids,
             const std::vector<ExpressionType> &expr_types,
             ScanDirectionType scan_direction,
             std::vector<ItemPointer *> &result,
             const ConjunctionScanPredicate *scan_predicate) override;
 
-  /// Perform a limited scan
+  /**
+   * ArtIndex throws away the first three arguments and only uses the conjuncts
+   * from the scan predicate.
+   *
+   * @param scan_predicate The only parameter that's used
+   * @param[out] result Where the results of the scan are stored
+   * @param limit How many results to actually return
+   * @param offset How many items to exclude from the results
+   */
   void ScanLimit(const std::vector<type::Value> &values,
                  const std::vector<oid_t> &key_column_ids,
                  const std::vector<ExpressionType> &expr_types,
@@ -66,10 +81,8 @@ class ArtIndex : public Index {
                  const ConjunctionScanPredicate *scan_predicate, uint64_t limit,
                  uint64_t offset) override;
 
-  /// Scan the entire index, placing results in the provided result vector
   void ScanAllKeys(std::vector<ItemPointer *> &result) override;
 
-  /// Scan all values for the given key, placing results in the provided vector
   void ScanKey(const storage::Tuple *key,
                std::vector<ItemPointer *> &result) override;
 
@@ -81,19 +94,30 @@ class ArtIndex : public Index {
   // TODO(pmenon): Implement me
   size_t GetMemoryFootprint() override { return 0; }
 
-  /// Does the index need GC
   // TODO(pmenon): Implement me
   bool NeedGC() override { return false; }
 
-  /// Perform any necessary GC on the index
   // TODO(pmenon): Implement me
   void PerformGC() override {}
 
-  /// These two functions are for testing so we can inject custom key loading
-  /// functions without bringing up a full-blown database/table.
+  /**
+   * Configure the load-key function for this index. The load-key function
+   * retrieves the key associated with a given value in the tree. This is
+   * necessary because an ART index does not always store the whole key in the
+   * tree due to prefix compression.
+   *
+   * @param load_func The loading key function pointer
+   * @param ctx An opaque pointer to some user-provided context. This context is
+   * passed as the first argument to the load-key function on each invocation.
+   */
   void SetLoadKeyFunc(art::Tree::LoadKeyFunction load_func, void *ctx);
 
-  /// Construct an ART key from a Peloton key
+  /**
+   * Convert the provided Peloton key into an ART-based key
+   *
+   * @param tuple The input key we'd like to convert
+   * @param[out] key Where the art-compatible key is written to
+   */
   void ConstructArtKey(const AbstractTuple &tuple, art::Key &key) const {
     key_constructor_.ConstructKey(tuple, key);
   }
@@ -112,10 +136,21 @@ class ArtIndex : public Index {
     explicit KeyConstructor(const catalog::Schema &key_schema)
         : key_schema_(key_schema) {}
 
-    /// Given an input Peloton key, construct an equivalent art::Key
+    /**
+     * Given an input Peloton key, construct an equivalent art::Key
+     *
+     * @param input_key The input (i.e., Peloton key)
+     * @param[out] tree_key Where the tree-compatible key is written
+     */
     void ConstructKey(const AbstractTuple &input_key, art::Key &tree_key) const;
 
-    /// Generate the minimum and maximum key
+    /**
+     * Generate the minimum and maximum key, storing the results in the provided
+     * min_key and max_key function parameters
+     *
+     * @param[out] min_key Where the minimum key is written
+     * @param[out] max_key Where the maximum key is written
+     */
     void ConstructMinMaxKey(art::Key &min_key, art::Key &max_key) const;
 
    private: