/ 
Bit-Set-0.02
/ Bit::Set::DB

NAME

Bit::Set::DB - Perl interface for bitset containers from the 'bit' C library

VERSION

version 0.02

SYNOPSIS

use Bit::Set::DB;
use Bit::Set;

# Create a new bitset database
my $db = BitDB_new(1024, 10);

# Create a bitset and add it to the database
my $set = Bit::Set::Bit_new(1024);
Bit::Set::Bit_bset($set, 42);
BitDB_put_at($db, 0, $set);

# Get population count at index
my $count = BitDB_count_at($db, 0);

# Free the database and bitset
BitDB_free(\$db);
Bit::Set::Bit_free(\$set);

DESCRIPTION

This module provides a procedural Perl interface to the C library 'bit.h', for creating and manipulating containers of bitsets (BitDB). It uses FFI::Platypus to wrap the C functions and Alien::Bit to locate and link to the C library.

The API is a direct mapping of the C functions. For detailed semantics of each function, please refer to the bit.h header file documentation.

Runtime checks on arguments are performed if the DEBUG environment variable is set to a true value.

FUNCTIONS

Creation and Destruction

BitDB_new(length, num_of_bitsets)

Creates a new bitset container for num_of_bitsets bitsets, each of length.

BitDB_free(db_ref)

Frees the memory associated with the bitset container. Expects a reference to the scalar holding the DB object.

Properties

BitDB_length(set)

Returns the length of bitsets in the container.

BitDB_nelem(set)

Returns the number of bitsets in the container.

BitDB_count_at(set, index)

Returns the population count of the bitset at the given index.

BitDB_count(set)

Returns a pointer to an array of population counts for all bitsets in the container.

Manipulation

BitDB_get_from(set, index)

Returns a bitset from the container at the given index.

BitDB_put_at(set, index, bitset)

Puts a bitset into the container at the given index.

BitDB_extract_from(set, index, buffer)

Extracts a bitset from the container at index into a buffer.

BitDB_replace_at(set, index, buffer)

Replaces a bitset in the container at index with the contents of a buffer.

BitDB_clear(set)

Clears all bitsets in the container.

BitDB_clear_at(set, index)

Clears the bitset at a given index in the container.

Set Operation Counts

These functions perform set operations between two bitset containers. The opts parameter is an object of type Bit::Set::DB::SETOP_COUNT_OPTS.

Example for opts:

my $opts = Bit::Set::DB::SETOP_COUNT_OPTS->new(
    num_cpu_threads => 4,
    device_id       => 0,
    # ... other flags
);
BitDB_inter_count_cpu(db1, db2, opts) =item BitDB_union_count_cpu(db1, db2, opts) =item BitDB_diff_count_cpu(db1, db2, opts) =item BitDB_minus_count_cpu(db1, db2, opts)

Perform the respective set operation count on the CPU.

BitDB_inter_count_gpu(db1, db2, opts) =item BitDB_union_count_gpu(db1, db2, opts) =item BitDB_diff_count_gpu(db1, db2, opts) =item BitDB_minus_count_gpu(db1, db2, opts)

Perform the respective set operation count on the GPU.

BitDB_inter_count_store_cpu(db1, db2, buffer, opts) =item BitDB_union_count_store_cpu(db1, db2, buffer, opts) =item BitDB_diff_count_store_cpu(db1, db2, buffer, opts) =item BitDB_minus_count_store_cpu(db1, db2, buffer, opts)

Perform the respective set operation count on the CPU and store results in buffer.

BitDB_inter_count_store_gpu(db1, db2, buffer, opts) =item BitDB_union_count_store_gpu(db1, db2, buffer, opts) =item BitDB_diff_count_store_gpu(db1, db2, buffer, opts) =item BitDB_minus_count_store_gpu(db1, db2, buffer, opts)

Perform the respective set operation count on the GPU and store results in buffer.

AUTHOR

GitHub Copilot (Claude Sonnet 4), guided by Christos Argyropoulos.

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Christos Argyropoulos.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.