Implement set union and (approximate) intersection for bloom filters

Given two bloom filters it is often useful to be able to compute their
union and intersection. That is, suppose we have two sets A and B, denote
by f(.) the construction of a bloom filter with a given set of parameters.
Then we would like to be able to (approximate) f(A v B) and f(A ^ B) given
f(A) and f(B). The union operation is exact, and obtained by the bitwise or
of fingerprints, so we have f(A v B) = f(A) v f(B).
In contrast the intersection, obtained by bitwise and of the fingerprints
is only approximate so we have f(A ^ B) ~= f(A) ^ f(B).

- Closes #602.

Author: wence-

doxygen/Doxyfile

@@ -1508,7 +1508,7 @@ FORMULA_MACROFILE      =
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-USE_MATHJAX            = NO
+USE_MATHJAX            = YES
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. See the MathJax site (see:

include/cuco/bloom_filter.cuh

@@ -42,7 +42,7 @@ namespace cuco {
  * - Host-side "bulk" operations
  * - Device-side "singular" operations
  *
- * The host-side bulk operations include `add`, `contains`, etc. These APIs should be used when
+ * The host-side bulk operations include add(), contains(), etc. These APIs should be used when
  * there are a large number of keys to add or lookup. For example, given a range of keys
  * specified by device-accessible iterators, the bulk `add` function will add all keys into
  * the filter.
@@ -124,7 +124,7 @@ class bloom_filter {
    * @brief Erases all information from the filter.
    *
    * @note This function synchronizes the given stream. For asynchronous execution use
-   * `clear_async`.
+   * clear_async().
    *
    * @param stream CUDA stream used for device memory operations and kernel launches
    */
@@ -142,7 +142,7 @@ class bloom_filter {
    * @brief Adds all keys in the range `[first, last)` to the filter.
    *
    * @note This function synchronizes the given stream. For asynchronous execution use
-   * `add_async`.
+   * add_async().
    *
    * @tparam InputIt Device-accessible random access input key iterator
    * @param first Beginning of the sequence of keys
@@ -173,7 +173,7 @@ class bloom_filter {
    *
    * @note The key `*(first + i)` is added if `pred( *(stencil + i) )` returns `true`.
    * @note This function synchronizes the given stream and returns the number of successful
-   * insertions. For asynchronous execution use `add_if_async`.
+   * insertions. For asynchronous execution use add_if_async().
    *
    * @tparam InputIt Device-accessible random access input key iterator
    * @tparam StencilIt Device-accessible random-access iterator whose `value_type` is
@@ -227,7 +227,7 @@ class bloom_filter {
    * filter.
    *
    * @note This function synchronizes the given stream. For asynchronous execution use
-   * `contains_async`.
+   * contains_async().
    *
    * @tparam InputIt Device-accessible random access input key iterator
    * @tparam OutputIt Device-accessible output iterator assignable from `bool`
@@ -269,7 +269,7 @@ class bloom_filter {
    *
    * @note The key `*(first + i)` is queried if `pred( *(stencil + i) )` returns `true`.
    * @note This function synchronizes the given stream. For asynchronous execution use
-   * `contains_if_async`.
+   * contains_if_async().
    *
    * @tparam InputIt Device-accessible random access input key iterator
    * @tparam StencilIt Device-accessible random-access iterator whose `value_type` is
@@ -325,6 +325,85 @@ class bloom_filter {
                                             cuda::stream_ref stream = cuda::stream_ref{
                                               cudaStream_t{nullptr}}) const noexcept;
 
+  /**
+   * @brief Merge another bloom filter into this.
+   *
+   * @note Modifies `this` in place.
+   * @note This function synchronizes the given stream. For asynchronous execution use
+   * merge_async().
+   *
+   * @note This performs the set union of the two filters. Let \f$f : X \to B\f$ denote the
+   * construction of a bloom filter on some set \f$X\f$, and let \f$A\f$ and \f$B\f$ be two sets,
+   * then it holds that \f$f(A \cup B) = f(A) \cup f(B)\f$.
+   *
+   * @param other Other filter with matching type to this.
+   * @param stream CUDA stream used for device memory operations and kernel launches.
+   *
+   * @throws cuco::logic_error If the other filter does not have the same number of blocks as this.
+   */
+  __host__ constexpr void merge(bloom_filter<Key, Extent, Scope, Policy, Allocator> const& other,
+                                cuda::stream_ref stream = cuda::stream_ref{cudaStream_t{nullptr}});
+
+  /**
+   * @brief Asynchronously merge another bloom filter into this.
+   *
+   * @note Modifies `this` in place.
+   *
+   * @note This performs the set union of the two filters. Let \f$f : X \to B\f$ denote the
+   * construction of a bloom filter on some set \f$X\f$, and let \f$A\f$ and \f$B\f$ be two sets,
+   * then it holds that \f$f(A \cup B) = f(A) \cup f(B)\f$
+   *
+   * @param other Other filter with matching type to this.
+   * @param stream CUDA stream used for device memory operations and kernel launches.
+   *
+   * @throws cuco::logic_error If the other filter does not have the same number of blocks as this.
+   */
+  __host__ constexpr void merge_async(
+    bloom_filter<Key, Extent, Scope, Policy, Allocator> const& other,
+    cuda::stream_ref stream = cuda::stream_ref{cudaStream_t{nullptr}});
+
+  /**
+   * @brief Intersect another bloom filter into this.
+   *
+   * @note Modifies `this` in place.
+   * @note This function synchronizes the given stream. For asynchronous execution use
+   * intersect_async().
+   *
+   * @note This performs the set intersection of the two filters. Unlike merge(), this operation
+   * does not distribute over filter construction and therefore only approximates the bloom filter
+   * of the intersection of the input sets. In other words, let \f$f : X \to B\f$ denote the
+   * construction of a bloom filter on some set \f$X\f$, and let \f$A\f$ and \f$B\f$ be two sets,
+   * then \f$(A \cap B) \ne f(A) \cap f(B)\f$.
+   *
+   * @param other Other filter with matching type to this.
+   * @param stream CUDA stream used for device memory operations and kernel launches.
+   *
+   * @throws cuco::logic_error If the other filter does not have the same number of blocks as this.
+   */
+  __host__ constexpr void intersect(
+    bloom_filter<Key, Extent, Scope, Policy, Allocator> const& other,
+    cuda::stream_ref stream = cuda::stream_ref{cudaStream_t{nullptr}});
+
+  /**
+   * @brief Asynchronously intersect another bloom filter into this.
+   *
+   * @note Modifies `this` in place.
+   *
+   * @note This performs the set intersection of the two filters. Unlike merge_async(), this
+   * operation does not distribute over filter construction and therefore only approximates the
+   * bloom filter of the intersection of the input sets. In other words, let \f$f : X \to B\f$
+   * denote the construction of a bloom filter on some set \f$X\f$, and let \f$A\f$ and \f$B\f$ be
+   * two sets, then \f$(A \cap B) \ne f(A) \cap f(B)\f$.
+   *
+   * @param other Other filter with matching type to this.
+   * @param stream CUDA stream used for device memory operations and kernel launches.
+   *
+   * @throws cuco::logic_error If the other filter does not have the same number of blocks as this.
+   */
+  __host__ constexpr void intersect_async(
+    bloom_filter<Key, Extent, Scope, Policy, Allocator> const& other,
+    cuda::stream_ref stream = cuda::stream_ref{cudaStream_t{nullptr}});
+
   /**
    * @brief Gets a pointer to the underlying filter storage.
    *
@@ -369,4 +448,4 @@ class bloom_filter {
 };
 }  // namespace cuco
 
-#include <cuco/detail/bloom_filter/bloom_filter.inl>
+#include <cuco/detail/bloom_filter/bloom_filter.inl>

include/cuco/bloom_filter_ref.cuh

@@ -97,7 +97,7 @@ class bloom_filter_ref {
    * @brief Erases all information from the filter.
    *
    * @note This function synchronizes the given stream. For asynchronous execution use
-   * `clear_async`.
+   * clear_async().
    *
    * @param stream CUDA stream used for device memory operations and kernel launches
    */
@@ -114,7 +114,7 @@ class bloom_filter_ref {
   /**
    * @brief Device function that adds a key to the filter.
    *
-   * @tparam ProbeKey Input type that is implicitly convertible to `key_type`
+   * @tparam ProbeKey Input type that is implicitly convertible to @ref key_type
    *
    * @param key The key to be added
    */
@@ -124,7 +124,7 @@ class bloom_filter_ref {
   /**
    * @brief Device function that cooperatively adds a key to the filter.
    *
-   * @note Best performance is achieved if the size of the CG is equal to `words_per_block`.
+   * @note Best performance is achieved if the size of the CG is equal to @ref words_per_block.
    *
    * @tparam CG Cooperative Group type
    * @tparam ProbeKey Input key type
@@ -139,7 +139,7 @@ class bloom_filter_ref {
    * @brief Device function that adds all keys in the range `[first, last)` to the filter.
    *
    * @note Best performance is achieved if the size of the CG is larger than or equal to
-   * `words_per_block`.
+   * @ref words_per_block.
    *
    * @tparam CG Cooperative Group type
    * @tparam InputIt Device-accessible random access input key iterator
@@ -155,7 +155,7 @@ class bloom_filter_ref {
    * @brief Adds all keys in the range `[first, last)` to the filter.
    *
    * @note This function synchronizes the given stream. For asynchronous execution use
-   * `add_async`.
+   * add_async().
    *
    * @tparam InputIt Device-accessible random access input key iterator
    *
@@ -187,7 +187,7 @@ class bloom_filter_ref {
    *
    * @note The key `*(first + i)` is added if `pred( *(stencil + i) )` returns `true`.
    * @note This function synchronizes the given stream and returns the number of successful
-   * insertions. For asynchronous execution use `add_if_async`.
+   * insertions. For asynchronous execution use add_if_async().
    *
    * @tparam InputIt Device-accessible random access input key iterator
    * @tparam StencilIt Device-accessible random-access iterator whose `value_type` is
@@ -275,7 +275,7 @@ class bloom_filter_ref {
    * filter.
    *
    * @note This function synchronizes the given stream. For asynchronous execution use
-   * `contains_async`.
+   * contains_async().
    *
    * @tparam InputIt Device-accessible random access input iterator where
    * <tt>std::is_convertible<std::iterator_traits<InputIt>::value_type,
@@ -321,7 +321,7 @@ class bloom_filter_ref {
    *
    * @note The key `*(first + i)` is queried if `pred( *(stencil + i) )` returns `true`.
    * @note This function synchronizes the given stream. For asynchronous execution use
-   * `contains_if_async`.
+   * contains_if_async().
    *
    * @tparam InputIt Device-accessible random access input iterator where
    * <tt>std::is_convertible<std::iterator_traits<InputIt>::value_type,
@@ -381,6 +381,85 @@ class bloom_filter_ref {
                                             cuda::stream_ref stream = cuda::stream_ref{
                                               cudaStream_t{nullptr}}) const noexcept;
 
+  /**
+   * @brief Merge another bloom filter into this.
+   *
+   * @note Modifies `this` in place.
+   * @note This function synchronizes the given stream. For asynchronous execution use
+   * merge_async().
+   *
+   * @note This performs the set union of the two filters. Let \f$f : X \to B\f$ denote the
+   * construction of a bloom filter on some set \f$X\f$, and let \f$A\f$ and \f$B\f$ be two sets,
+   * then it holds that \f$f(A \cup B) = f(A) \cup f(B)\f$.
+   *
+   * @param other Other filter with matching type to this.
+   * @param stream CUDA stream used for device memory operations and kernel launches.
+   *
+   * @throws cuco::logic_error If the other filter does not have the same number of blocks as this.
+   */
+  __host__ constexpr void merge(bloom_filter_ref<Key, Extent, Scope, Policy> const& other,
+                                cuda::stream_ref stream = cuda::stream_ref{cudaStream_t{nullptr}});
+
+  /**
+   * @brief Asynchronously merge another bloom filter into this.
+   *
+   * @note Modifies `this` in place.
+   *
+   * @note This performs the set union of the two filters. Let \f$f : X \to B\f$ denote the
+   * construction of a bloom filter on some set \f$X\f$, and let \f$A\f$ and \f$B\f$ be two sets,
+   * then it holds that \f$f(A \cup B) = f(A) \cup f(B)\f$
+   *
+   * @param other Other filter with matching type to this.
+   * @param stream CUDA stream used for device memory operations and kernel launches.
+   *
+   * @throws cuco::logic_error If the other filter does not have the same number of blocks as this.
+   */
+  __host__ constexpr void merge_async(bloom_filter_ref<Key, Extent, Scope, Policy> const& other,
+                                      cuda::stream_ref stream = cuda::stream_ref{
+                                        cudaStream_t{nullptr}});
+
+  /**
+   * @brief Intersect another bloom filter into this.
+   *
+   * @note Modifies `this` in place.
+   * @note This function synchronizes the given stream. For asynchronous execution use
+   * intersect_async().
+   *
+   * @note This performs the set intersection of the two filters. Unlike merge(), this operation
+   * does not distribute over filter construction and therefore only approximates the bloom filter
+   * of the intersection of the input sets. In other words, let \f$f : X \to B\f$ denote the
+   * construction of a bloom filter on some set \f$X\f$, and let \f$A\f$ and \f$B\f$ be two sets,
+   * then \f$f(A \cap B) \ne f(A) \cap f(B)\f$.
+   *
+   * @param other Other filter with matching type to this.
+   * @param stream CUDA stream used for device memory operations and kernel launches.
+   *
+   * @throws cuco::logic_error If the other filter does not have the same number of blocks as this.
+   */
+  __host__ constexpr void intersect(bloom_filter_ref<Key, Extent, Scope, Policy> const& other,
+                                    cuda::stream_ref stream = cuda::stream_ref{
+                                      cudaStream_t{nullptr}});
+
+  /**
+   * @brief Asynchronously intersect another bloom filter into this.
+   *
+   * @note Modifies `this` in place.
+   *
+   * @note This performs the set intersection of the two filters. Unlike merge_async(), this
+   * operation does not distribute over filter construction and therefore only approximates the
+   * bloom filter of the intersection of the input sets. In other words, let \f$f : X \to B\f$
+   * denote the construction of a bloom filter on some set \f$X\f$, and let \f$A\f$ and \f$B\f$ be
+   * two sets, then \f$f(A \cap B) \ne f(A) \cap f(B)\f$.
+   *
+   * @param other Other filter with matching type to this.
+   * @param stream CUDA stream used for device memory operations and kernel launches.
+   *
+   * @throws cuco::logic_error If the other filter does not have the same number of blocks as this.
+   */
+  __host__ constexpr void intersect_async(bloom_filter_ref<Key, Extent, Scope, Policy> const& other,
+                                          cuda::stream_ref stream = cuda::stream_ref{
+                                            cudaStream_t{nullptr}});
+
   /**
    * @brief Gets a pointer to the underlying filter storage.
    *
@@ -407,4 +486,4 @@ class bloom_filter_ref {
 };
 }  // namespace cuco
 
-#include <cuco/detail/bloom_filter/bloom_filter_ref.inl>
+#include <cuco/detail/bloom_filter/bloom_filter_ref.inl>

include/cuco/detail/bloom_filter/bloom_filter.inl

@@ -129,6 +129,34 @@ __host__ constexpr void bloom_filter<Key, Extent, Scope, Policy, Allocator>::con
   ref_.contains_if_async(first, last, stencil, pred, output_begin, stream);
 }
 
+template <class Key, class Extent, cuda::thread_scope Scope, class Policy, class Allocator>
+__host__ constexpr void bloom_filter<Key, Extent, Scope, Policy, Allocator>::merge(
+  bloom_filter<Key, Extent, Scope, Policy, Allocator> const& other, cuda::stream_ref stream)
+{
+  ref_.merge(other.ref_, stream);
+}
+
+template <class Key, class Extent, cuda::thread_scope Scope, class Policy, class Allocator>
+__host__ constexpr void bloom_filter<Key, Extent, Scope, Policy, Allocator>::merge_async(
+  bloom_filter<Key, Extent, Scope, Policy, Allocator> const& other, cuda::stream_ref stream)
+{
+  ref_.merge_async(other.ref_, stream);
+}
+
+template <class Key, class Extent, cuda::thread_scope Scope, class Policy, class Allocator>
+__host__ constexpr void bloom_filter<Key, Extent, Scope, Policy, Allocator>::intersect(
+  bloom_filter<Key, Extent, Scope, Policy, Allocator> const& other, cuda::stream_ref stream)
+{
+  ref_.intersect(other.ref_, stream);
+}
+
+template <class Key, class Extent, cuda::thread_scope Scope, class Policy, class Allocator>
+__host__ constexpr void bloom_filter<Key, Extent, Scope, Policy, Allocator>::intersect_async(
+  bloom_filter<Key, Extent, Scope, Policy, Allocator> const& other, cuda::stream_ref stream)
+{
+  ref_.intersect_async(other.ref_, stream);
+}
+
 template <class Key, class Extent, cuda::thread_scope Scope, class Policy, class Allocator>
 [[nodiscard]] __host__ constexpr
   typename bloom_filter<Key, Extent, Scope, Policy, Allocator>::word_type*
@@ -169,4 +197,4 @@ template <class Key, class Extent, cuda::thread_scope Scope, class Policy, class
   return ref_;
 }
 
-}  // namespace cuco
+}  // namespace cuco