Implement set union and (approximate) intersection for bloom filters (#781)

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.

---------

Co-authored-by: Daniel Juenger <[email protected]>

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,91 @@ 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. The policy object must be equal to that
+   * of this filter, otherwise behavior is undefined.
+   * @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. The policy object must be equal to that
+   * of this filter, otherwise behavior is undefined.
+   * @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$. Despite this, it is guaranteed that for all \f$x \in
+   * (A \cap B)\f$, it holds \f$x \in f(A) \cap f(B)\f$.
+   *
+   * @param other Other filter with matching type to this. The policy object must be equal to that
+   * of this filter, otherwise behavior is undefined.
+   * @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$. Despite this, it is guaranteed that for
+   * all \f$x \in (A \cap B)\f$, it holds \f$x \in f(A) \cap f(B)\f$.
+   *
+   * @param other Other filter with matching type to this. The policy object must be equal to that
+   * of this filter, otherwise behavior is undefined.
+   * @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 +454,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,91 @@ 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. The policy object must be equal to that
+   * of this filter, otherwise behavior is undefined.
+   * @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. The policy object must be equal to that
+   * of this filter, otherwise behavior is undefined.
+   * @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$. Despite this, it is guaranteed that for all \f$x \in
+   * (A \cap B)\f$, it holds \f$x \in f(A) \cap f(B)\f$.
+   *
+   * @param other Other filter with matching type to this. The policy object must be equal to that
+   * of this filter, otherwise behavior is undefined.
+   * @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$. Despite this, it is guaranteed that for
+   * all \f$x \in (A \cap B)\f$, it holds \f$x \in f(A) \cap f(B)\f$.
+   *
+   * @param other Other filter with matching type to this. The policy object must be equal to that
+   * of this filter, otherwise behavior is undefined.
+   * @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 +492,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