dax_translate - translate each vector element to 0 or 1
cc [ flag... ] file... -ldax [ library...]
#include <dax.h>
dax_result_t
dax_translate(dax_context_t *ctx, uint64_t flags,
dax_vec_t *src, dax_vec_t *dst, dax_vec_t *bitmap,
unsigned val_width);
This function translates each element in src to 0 or 1 and writes the value to the corresponding element of the dst bit vector. It uses the value x of the ith element in src as an index into bitmap, and writes the xth element in bitmap to the ith element of the dst bit vector.
dst[i] = bitmap[src[i]];
The following rules apply during translation:
Width of the element in src may be any of the following:
1 to 16 bits or 1 to 3 bytes in libdax version 1
1 to 24 bits or 1 to 3 bytes in libdax version 2
src may be fixed width or run-length encoded, but cannot be zipped.
bitmap->elem_width must be 1 and format must be DAX_BITS.
bitmap->offset must be 0.
bitmap->data must be aligned on a 64 byte boundary.
bitmap->elements count must not exceed 16M.
val_width is the number of significant low-order bits of each element to use in the index value. It must be less than or equal to the width of the element.
High-order bits above val_width must be 0 in all elements. libdax checks these conditions only if the DAX_DEBUG_EXTRA debug option is set. If this condition is violated and not checked, you will get undefined results.
DAX supports bitmaps up to 32K bits natively, and up to 16M bits with reduced efficiency by making multiple passes over the src data. If the number of bitmap elements is less than the largest value in src plus 1, the results are undefined. The DAX_DEBUG_EXTRA debug option checks this condition.
The dst->offset field must be set to 0.
If you omit the DAX_ONES_INDEX flag, the width of the elements in dst must be 1 bit and the number of elements in dst must be at least the number of elements in src, where the latter number includes expansion from run-length encoding. If src is run-length encoded, this condition is only checked if the DAX_DEBUG_EXTRA debug option is set.
The data in dst must start on a 64 byte boundary. You must round up the size of the data in dst as described in the dax_vec_t(3DAX) man page.
The following address ranges must not overlap:
Address range of the src->data vector and the dst->data vector
Address range of the src->aux_data vector and the dst->data vector
The libdax library checks the overlap in the address ranges only if the DAX_DEBUG_EXTRA debug option is set. If violations of the conditions occur and are not checked, you will get undefined results.
Inverts the result of translation. 0 becomes 1, and 1 becomes 0.
Instead of writing a single 0 or 1 bit to dst for each element in src, write the index of the src element for which the translation is 1 (after inversion if specified). The indices start at 0. The width of the elements in dst may be 2 or 4 bytes, and correspondingly writes each index as a 2 or 4-byte big-endian word. If the index is too large for the word, writes the maximum unsigned value for the word in libdax versions 1 and 2. The number of elements in dst must be at least the number of elements that translate to 1. If this is not known, use the number of elements in src as an upper bound.
Limits the number of elements in src to 232 when you specify this flag. For the usage notes, see the dax_scan_value(3DAX) man page.
Writes results to cache. If not specified, invalidates the address range for dst in the cache, and writes the result to the main memory.
If the DAX command queue is full, returns without submitting the command, instead of waiting to submit.
Returns the number of elements that translate to 1 in the dax_result_t count field (after inversion if specified) and sets the dax_result_t status field to one of the following values:
Operation completed successfully
Invalid argument, detected by libdax
Invalid argument, detected by DAX
The true value of an aux_data element is 0, or the width of a zip symbol is less than 1 or greater than 8, detected by DAX.
Output buffer overflow
ADI mismatch error for an input or output buffer
The calling thread did not create ctx
DAX is busy and nowait was requested.
Unknown internal error. Caller must stop using ctx.
You can use the translate() function to test for set membership. The bitmap is a bit set, where element x is 1 if value x is a member of the set. The ith element in dst is 1 if the ith element in src is a member of the set.
For best performance, align the bitmap data to the value of the trans_bitmap_align_best property as defined in the dax_get_props(3DAX) man page.
See attributes(5) for descriptions of the following attributes:
|
libdax(3LIB), dax_vec_t(3DAX), dax_adi(3DAX), dax_dtrace(3DAX), dax_scan_value(3DAX), dax_zip(3DAX)