dax_scan_value - compare vector elements with a specified value
cc [ flag... ] file... -ldax [ library...]
#include <dax.h>
dax_result_t
dax_scan_value(dax_context_t *ctx, uint64_t flags,
dax_vec_t *src, dax_vec_t *dst, dax_compare_t op, dax_int_t *val);
This function compares each element of src to a single value by using the operation specified in op. If an element in src matches the user specified value, the corresponding bit in the dst vector is set to 1 else set to 0. All values are unsigned, with the most significant bit (MSB) on the left and decreasing bit significance moving to the right within a byte and to the next higher address byte.
If src is zipped, translates each code word of src by using the src codec and produces a 1 to 8 byte symbol which it appends to an intermediate unzip stream. It then partitions the unzip stream into elements at src->elem_width boundaries, repeats each element if src is run-length encoded, and compares it with val.
In a variable width src, the ith element of the src->aux_data field gives the width of the ith unzipped element.
In a run-length encoded src, the ith element of the src->aux_data field gives the repeat count of the ith unzipped element as described in the dax_vec_t(3DAX) man page. The aux_data field is not in zipped form.
The op parameter can be set to any one of the following values:
element == value
element != value
element < value
element <= value
element > value
element >= value
The src element width can be:
1 to 16 bits or 1 to 16 bytes in libdax version 1
1 to 24 bits or 1 to 16 bytes in libdax version 2
The src format may be fixed width, variable width, or run-length encoded.
The val argument contains a comparison value that is:
1 to 16 bits or 1 to 16 bytes wide in libdax version 1
1 to 24 bits or 1 to 16 bytes wide in libdax version 2
val has the following structure:
typedef struct {
uint32_t format;
uint32_t elem_width;
uint64_t dword[3];
} dax_int_t;
dword[0] is the high order word, dword[1] is the middle order word, and dword[2] is the low order word. Each word is big endian. The width of the value is given by elem_width, in units of bits if (format & DAX_BITS), else in units of bytes. The high order bytes above elem_width within the partially used dwords must be 0. Checks this condition only if the DAX_DEBUG_EXTRA debug option is set. Ignores the high order dwords that are above elem_width. For a fixed-width src, the elem_width value must match the width of the src element.
The following rules apply when comparing two values that have different widths:
Each value is round up to a byte-sized boundary, padded with 0 bits at the MSB as needed.
If the rounded widths are the same, apply normal comparison rules.
If the rounded widths differ, the values are not equal.
Compares the left most bytes by using the normal rules up to the width of the shorter value. If they match, the shorter element is smaller.
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. 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.
The flags parameter can be set to one or more following values:
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. 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.
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 matching elements in the dax_result_t count field 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.
The following examples show comparisons between elements with different widths. Each expression below is true.
"4" > "3"
"4" > "33"
"4" > "04"
"4" < "40"
The DAX_CACHE_DST flag generally improves performance if the size of the results is small relative to the cachesize, and the program uses the data soon after the function completes. It may reduce performance if the result is large and displaces other useful data from the cache.
The DAX_ONES_INDEX flag improves performance if the selectivity of the scan is low, which means that a small percentage of src elements produce the comparison result as true. The size of dst in bytes can be smaller, and software can efficiently select the elements in src by using the indices. When you use a 4-byte index, the dst size is smaller if selectivity is less than 1/32. But if selectivity is 100%, the size of dst is 32 times larger with DAX_ONES_INDEX.
See attributes(5) for descriptions of the following attributes:
|
libdax(3LIB), dax_vec_t(3DAX), dax_adi(3DAX), dax_dtrace(3DAX), dax_int_create(3DAX), dax_zip(3DAX)