4 // A reimplementation of parts of the TurboPFor codecs, using the same
5 // storage format. These are not as fast as the reference implementation
6 // (about 60% of the performance, averaged over a real plocate corpus),
7 // and do not support the same breadth of codecs (in particular, only
8 // delta-plus-1 is implemented, and only 32-bit docids are tested),
9 // but aim to be more portable and (ideally) easier-to-understand.
10 // In particular, they will compile on x86 without SSE4.1 or AVX support.
12 // The main reference is https://michael.stapelberg.ch/posts/2019-02-05-turbopfor-analysis/,
13 // although some implementation details have been worked out by studying the
24 #if defined(__i386__) || defined(__x86_64__)
25 #define COULD_HAVE_SSE2
26 #include <immintrin.h>
29 // Forward declarations to declare to the template code below that they exist.
30 // (These must seemingly be non-templates for function multiversioning to work.)
31 __attribute__((target("default")))
32 const unsigned char *decode_for_interleaved_128_32(const unsigned char *in, uint32_t *out);
33 __attribute__((target("default")))
34 const unsigned char *decode_pfor_bitmap_interleaved_128_32(const unsigned char *in, uint32_t *out);
35 __attribute__((target("default")))
36 const unsigned char *decode_pfor_vb_interleaved_128_32(const unsigned char *in, uint32_t *out);
38 #ifdef COULD_HAVE_SSE2
39 __attribute__((target("sse2")))
40 const unsigned char *decode_for_interleaved_128_32(const unsigned char *in, uint32_t *out);
41 __attribute__((target("sse2")))
42 const unsigned char *decode_pfor_bitmap_interleaved_128_32(const unsigned char *in, uint32_t *out);
43 __attribute__((target("sse2")))
44 const unsigned char *decode_pfor_vb_interleaved_128_32(const unsigned char *in, uint32_t *out);
47 constexpr uint32_t mask_for_bits(unsigned bit_width)
49 if (bit_width == 32) {
52 return (1U << bit_width) - 1;
57 Docid read_le(const void *in)
60 memcpy(&val, in, sizeof(val));
61 if constexpr (sizeof(Docid) == 8) {
63 } else if constexpr (sizeof(Docid) == 4) {
65 } else if constexpr (sizeof(Docid) == 2) {
67 } else if constexpr (sizeof(Docid) == 1) {
74 // Reads a single value with an encoding that looks a bit like PrefixVarint.
75 // It's unclear why this doesn't use the varbyte encoding.
77 const unsigned char *read_baseval(const unsigned char *in, Docid *out)
79 //fprintf(stderr, "baseval: 0x%02x 0x%02x 0x%02x 0x%02x\n", in[0], in[1], in[2], in[3]);
83 } else if (*in < 192) {
84 *out = ((uint32_t(in[0]) << 8) | uint32_t(in[1])) & 0x3fff;
86 } else if (*in < 224) {
87 *out = ((uint32_t(in[0]) << 16) |
88 (uint32_t(in[2]) << 8) |
89 (uint32_t(in[1]))) & 0x1fffff;
92 assert(false); // Not implemented.
97 const unsigned char *read_vb(const unsigned char *in, Docid *out)
102 } else if (*in <= 240) {
103 *out = ((uint32_t(in[0] - 177) << 8) | uint32_t(in[1])) + 177;
105 } else if (*in <= 248) {
106 *out = ((uint32_t(in[0] - 241) << 16) | read_le<uint16_t>(in + 1)) + 16561;
108 } else if (*in == 249) {
109 *out = (uint32_t(in[1])) |
110 (uint32_t(in[2]) << 8) |
111 (uint32_t(in[3]) << 16);
113 } else if (*in == 250) {
114 *out = read_le<uint32_t>(in + 1);
123 BitReader(const unsigned char *in, unsigned bits)
124 : in(in), bits(bits), mask(mask_for_bits(bits)) {}
127 uint32_t val = (read_le<uint32_t>(in) >> bits_used) & mask;
137 const unsigned char *in;
140 unsigned bits_used = 0;
143 template<unsigned NumStreams>
144 struct InterleavedBitReader {
146 InterleavedBitReader(const unsigned char *in, unsigned bits)
147 : in(in), bits(bits), mask(mask_for_bits(bits)) {}
151 if (bits_used + bits > 32) {
152 val = (read_le<uint32_t>(in) >> bits_used) | (read_le<uint32_t>(in + Stride) << (32 - bits_used));
154 val = (read_le<uint32_t>(in) >> bits_used);
158 in += Stride * (bits_used / 32);
165 static constexpr unsigned Stride = NumStreams * sizeof(uint32_t);
166 const unsigned char *in;
169 unsigned bits_used = 0;
172 #ifdef COULD_HAVE_SSE2
173 struct InterleavedBitReaderSSE2 {
175 InterleavedBitReaderSSE2(const unsigned char *in, unsigned bits)
176 : in(reinterpret_cast<const __m128i *>(in)), bits(bits), mask(_mm_set1_epi32(mask_for_bits(bits))) {}
178 __m128i val = _mm_srli_epi32(_mm_loadu_si128(in), bits_used);
179 if (bits_used + bits > 32) {
180 __m128i val_upper = _mm_slli_epi32(_mm_loadu_si128(in + 1), 32 - bits_used);
181 val = _mm_or_si128(val, val_upper);
183 val = _mm_and_si128(val, mask);
186 in += bits_used / 32;
195 unsigned bits_used = 0;
199 // Does not properly account for overflow.
200 inline unsigned div_round_up(unsigned val, unsigned div)
202 return (val + div - 1) / div;
205 inline unsigned bytes_for_packed_bits(unsigned num, unsigned bit_width)
207 return div_round_up(num * bit_width, CHAR_BIT);
210 // Constant block. Layout:
212 // - Bit width (6 bits) | type << 6
213 // - Base values (<bits> bits, rounded up to nearest byte)
214 template<class Docid>
215 const unsigned char *decode_constant(const unsigned char *in, unsigned num, Docid *out)
217 const unsigned bit_width = *in++ & 0x3f;
218 Docid val = read_le<Docid>(in);
219 if (bit_width < sizeof(Docid) * 8) {
220 val &= mask_for_bits(bit_width);
223 Docid prev_val = out[-1];
224 for (unsigned i = 0; i < num; ++i) {
225 out[i] = prev_val = val + prev_val + 1;
227 return in + div_round_up(bit_width, 8);
230 // FOR block (ie., PFor without exceptions). Layout:
232 // - Bit width (6 bits) | type << 6
233 // - Base values (<num> values of <bits> bits, rounded up to a multiple of 32 values)
234 template<class Docid>
235 const unsigned char *decode_for(const unsigned char *in, unsigned num, Docid *out)
237 const unsigned bit_width = *in++ & 0x3f;
239 Docid prev_val = out[-1];
240 BitReader bs(in, bit_width);
241 for (unsigned i = 0; i < num; ++i) {
242 prev_val = out[i] = bs.read() + prev_val + 1;
244 return in + bytes_for_packed_bits(num, bit_width);
247 #ifdef COULD_HAVE_SSE2
248 class DeltaDecoderSSE2 {
250 DeltaDecoderSSE2(uint32_t prev_val) : prev_val(_mm_set1_epi32(prev_val)) {}
251 __m128i decode(__m128i val) {
252 val = _mm_add_epi32(val, _mm_slli_si128(val, 4));
253 val = _mm_add_epi32(val, _mm_slli_si128(val, 8));
254 val = _mm_add_epi32(val, _mm_add_epi32(prev_val, delta));
255 prev_val = _mm_shuffle_epi32(val, _MM_SHUFFLE(3, 3, 3, 3));
260 // Use 4/3/2/1 as delta instead of fixed 1, so that we can do the prev_val + delta
261 // in parallel with something else.
262 const __m128i delta = _mm_set_epi32(4, 3, 2, 1);
267 template<unsigned BlockSize>
268 __attribute__((target("sse2")))
269 inline void delta_decode_sse2(uint32_t *out)
271 DeltaDecoderSSE2 delta(out[-1]);
272 __m128i *outvec = reinterpret_cast<__m128i *>(out);
273 for (unsigned i = 0; i < BlockSize / 4; ++i) {
274 __m128i val = _mm_loadu_si128(outvec + i);
275 _mm_storeu_si128(outvec + i, delta.decode(val));
279 template<unsigned BlockSize, bool OrWithExisting, bool DeltaDecode>
280 __attribute__((target("sse2")))
281 const unsigned char *decode_bitmap_sse2(const unsigned char *in, unsigned bit_width, uint32_t *out)
283 __m128i *outvec = reinterpret_cast<__m128i *>(out);
284 DeltaDecoderSSE2 delta(out[-1]);
285 InterleavedBitReaderSSE2 bs(in, bit_width);
286 for (unsigned i = 0; i < BlockSize / 4; ++i) {
287 __m128i val = bs.read();
288 if constexpr (OrWithExisting) {
289 val = _mm_or_si128(val, _mm_loadu_si128(outvec + i));
291 if constexpr (DeltaDecode) {
292 val = delta.decode(val);
294 _mm_storeu_si128(outvec + i, val);
296 in += bytes_for_packed_bits(BlockSize, bit_width);
301 // Like decode_for(), but the values are organized in four independent streams,
302 // for SIMD (presumably SSE2). Supports a whole block only.
303 template<unsigned BlockSize, class Docid>
304 const unsigned char *decode_for_interleaved_generic(const unsigned char *in, Docid *out)
306 const unsigned bit_width = *in++ & 0x3f;
308 InterleavedBitReader<4> bs0(in + 0 * sizeof(uint32_t), bit_width);
309 InterleavedBitReader<4> bs1(in + 1 * sizeof(uint32_t), bit_width);
310 InterleavedBitReader<4> bs2(in + 2 * sizeof(uint32_t), bit_width);
311 InterleavedBitReader<4> bs3(in + 3 * sizeof(uint32_t), bit_width);
312 for (unsigned i = 0; i < BlockSize / 4; ++i) {
313 out[i * 4 + 0] = bs0.read();
314 out[i * 4 + 1] = bs1.read();
315 out[i * 4 + 2] = bs2.read();
316 out[i * 4 + 3] = bs3.read();
318 Docid prev_val = out[-1];
319 for (unsigned i = 0; i < BlockSize; ++i) {
320 out[i] = prev_val = out[i] + prev_val + 1;
322 return in + bytes_for_packed_bits(BlockSize, bit_width);
325 template<unsigned BlockSize, class Docid>
326 const unsigned char *decode_for_interleaved(const unsigned char *in, Docid *out)
328 if constexpr (BlockSize == 128 && sizeof(Docid) == sizeof(uint32_t)) {
329 return decode_for_interleaved_128_32(in, out);
331 return decode_for_interleaved_generic(in, out);
335 __attribute__((target("default")))
336 const unsigned char *decode_for_interleaved_128_32(const unsigned char *in, uint32_t *out)
338 return decode_for_interleaved_generic<128>(in, out);
341 #ifdef COULD_HAVE_SSE2
342 // Specialized version for SSE2.
343 __attribute__((target("sse2")))
344 const unsigned char *decode_for_interleaved_128_32(const unsigned char *in, uint32_t *out)
346 constexpr unsigned BlockSize = 128;
348 const unsigned bit_width = *in++ & 0x3f;
350 in = decode_bitmap_sse2<BlockSize, /*OrWithExisting=*/false, /*DeltaDecode=*/true>(in, bit_width, out);
356 template<class Docid>
357 const unsigned char *decode_pfor_bitmap_exceptions(const unsigned char *in, unsigned num, unsigned bit_width, Docid *out)
359 const unsigned exception_bit_width = *in++;
360 const uint64_t *exception_bitmap_ptr = reinterpret_cast<const uint64_t *>(in);
361 in += div_round_up(num, 8);
363 int num_exceptions = 0;
365 BitReader bs(in, exception_bit_width);
366 for (unsigned i = 0; i < num; i += 64, ++exception_bitmap_ptr) {
367 uint64_t exceptions = read_le<uint64_t>(exception_bitmap_ptr);
369 // We've read some bytes past the end, so clear out the junk bits.
370 exceptions &= (1ULL << (num - i)) - 1;
372 for (; exceptions != 0; exceptions &= exceptions - 1, ++num_exceptions) {
373 unsigned idx = (ffsll(exceptions) - 1) + i;
374 out[idx] = bs.read() << bit_width;
377 in += bytes_for_packed_bits(num_exceptions, exception_bit_width);
381 // PFor block with bitmap exceptions. Layout:
383 // - Bit width (6 bits) | type << 6
384 // - Exception bit width (8 bits)
385 // - Bitmap of which values have exceptions (<num> bits, rounded up to a byte)
386 // - Exceptions (<num_exc> values of <bits_exc> bits, rounded up to a byte)
387 // - Base values (<num> values of <bits> bits, rounded up to a byte)
388 template<class Docid>
389 const unsigned char *decode_pfor_bitmap(const unsigned char *in, unsigned num, Docid *out)
391 memset(out, 0, num * sizeof(Docid));
393 const unsigned bit_width = *in++ & 0x3f;
395 in = decode_pfor_bitmap_exceptions(in, num, bit_width, out);
397 // Decode the base values, and delta-decode.
398 Docid prev_val = out[-1];
399 BitReader bs(in, bit_width);
400 for (unsigned i = 0; i < num; ++i) {
401 out[i] = prev_val = (out[i] | bs.read()) + prev_val + 1;
403 return in + bytes_for_packed_bits(num, bit_width);
406 // Like decode_pfor_bitmap(), but the base values are organized in four
407 // independent streams, for SIMD (presumably SSE2). Supports a whole block only.
408 template<unsigned BlockSize, class Docid>
409 const unsigned char *decode_pfor_bitmap_interleaved_generic(const unsigned char *in, Docid *out)
411 memset(out, 0, BlockSize * sizeof(Docid));
413 const unsigned bit_width = *in++ & 0x3f;
415 in = decode_pfor_bitmap_exceptions(in, BlockSize, bit_width, out);
417 // Decode the base values.
418 InterleavedBitReader<4> bs0(in + 0 * sizeof(uint32_t), bit_width);
419 InterleavedBitReader<4> bs1(in + 1 * sizeof(uint32_t), bit_width);
420 InterleavedBitReader<4> bs2(in + 2 * sizeof(uint32_t), bit_width);
421 InterleavedBitReader<4> bs3(in + 3 * sizeof(uint32_t), bit_width);
422 for (unsigned i = 0; i < BlockSize / 4; ++i) {
423 out[i * 4 + 0] |= bs0.read();
424 out[i * 4 + 1] |= bs1.read();
425 out[i * 4 + 2] |= bs2.read();
426 out[i * 4 + 3] |= bs3.read();
430 Docid prev_val = out[-1];
431 for (unsigned i = 0; i < BlockSize; ++i) {
432 out[i] = prev_val = out[i] + prev_val + 1;
434 return in + bytes_for_packed_bits(BlockSize, bit_width);
437 template<unsigned BlockSize, class Docid>
438 const unsigned char *decode_pfor_bitmap_interleaved(const unsigned char *in, Docid *out)
440 if constexpr (BlockSize == 128 && sizeof(Docid) == sizeof(uint32_t)) {
441 return decode_pfor_bitmap_interleaved_128_32(in, out);
443 return decode_pfor_bitmap_interleaved_generic(in, out);
447 __attribute__((target("default")))
448 const unsigned char *decode_pfor_bitmap_interleaved_128_32(const unsigned char *in, uint32_t *out)
450 return decode_pfor_bitmap_interleaved_generic<128>(in, out);
453 #ifdef COULD_HAVE_SSE2
454 // Specialized version for SSE2.
455 __attribute__((target("sse2")))
456 const unsigned char *decode_pfor_bitmap_interleaved_128_32(const unsigned char *in, uint32_t *out)
458 constexpr unsigned BlockSize = 128;
459 using Docid = uint32_t;
461 memset(out, 0, BlockSize * sizeof(Docid));
463 const unsigned bit_width = *in++ & 0x3f;
465 in = decode_pfor_bitmap_exceptions(in, BlockSize, bit_width, out);
466 in = decode_bitmap_sse2<BlockSize, /*OrWithExisting=*/true, /*DeltaDecode=*/true>(in, bit_width, out);
472 // PFor block with variable-byte exceptions. Layout:
474 // - Bit width (6 bits) | type << 6
475 // - Number of exceptions (8 bits)
476 // - Base values (<num> values of <bits> bits, rounded up to a byte)
478 // - If first byte is 255, <num_exc> 32-bit values (does not include the 255 byte)
479 // - Else, <num_exc> varbyte-encoded values (includes the non-255 byte)
480 // - Indexes of exceptions (<num_exc> bytes).
481 template<unsigned BlockSize, class Docid>
482 const unsigned char *decode_pfor_vb(const unsigned char *in, unsigned num, Docid *out)
484 //fprintf(stderr, "in=%p out=%p num=%u\n", in, out, num);
486 const unsigned bit_width = *in++ & 0x3f;
487 unsigned num_exceptions = *in++;
489 // Decode the base values.
490 BitReader bs(in, bit_width);
491 for (unsigned i = 0; i < num; ++i) {
494 in += bytes_for_packed_bits(num, bit_width);
496 // Decode exceptions.
497 Docid exceptions[BlockSize];
500 for (unsigned i = 0; i < num_exceptions; ++i) {
501 exceptions[i] = read_le<Docid>(in);
505 for (unsigned i = 0; i < num_exceptions; ++i) {
506 in = read_vb(in, &exceptions[i]);
510 for (unsigned i = 0; i < num_exceptions; ++i) {
511 unsigned idx = *in++;
512 out[idx] |= exceptions[i] << bit_width;
516 Docid prev_val = out[-1];
517 for (unsigned i = 0; i < num; ++i) {
518 out[i] = prev_val = out[i] + prev_val + 1;
524 // Like decode_pfor_vb(), but the base values are organized in four
525 // independent streams, for SIMD (presumably SSE2). Supports a whole block only.
526 template<unsigned BlockSize, class Docid>
527 const unsigned char *decode_pfor_vb_interleaved_generic(const unsigned char *in, Docid *out)
529 const unsigned bit_width = *in++ & 0x3f;
530 unsigned num_exceptions = *in++;
532 // Decode the base values.
533 InterleavedBitReader<4> bs0(in + 0 * sizeof(uint32_t), bit_width);
534 InterleavedBitReader<4> bs1(in + 1 * sizeof(uint32_t), bit_width);
535 InterleavedBitReader<4> bs2(in + 2 * sizeof(uint32_t), bit_width);
536 InterleavedBitReader<4> bs3(in + 3 * sizeof(uint32_t), bit_width);
537 for (unsigned i = 0; i < BlockSize / 4; ++i) {
538 out[i * 4 + 0] = bs0.read();
539 out[i * 4 + 1] = bs1.read();
540 out[i * 4 + 2] = bs2.read();
541 out[i * 4 + 3] = bs3.read();
543 in += bytes_for_packed_bits(BlockSize, bit_width);
545 // Decode exceptions.
546 Docid exceptions[BlockSize];
549 for (unsigned i = 0; i < num_exceptions; ++i) {
550 exceptions[i] = read_le<Docid>(in);
554 for (unsigned i = 0; i < num_exceptions; ++i) {
555 in = read_vb(in, &exceptions[i]);
560 for (unsigned i = 0; i < num_exceptions; ++i) {
561 unsigned idx = *in++;
562 out[idx] |= exceptions[i] << bit_width;
566 Docid prev_val = out[-1];
567 for (unsigned i = 0; i < BlockSize; ++i) {
568 out[i] = prev_val = out[i] + prev_val + 1;
574 template<unsigned BlockSize, class Docid>
575 const unsigned char *decode_pfor_vb_interleaved(const unsigned char *in, Docid *out)
577 if constexpr (BlockSize == 128 && sizeof(Docid) == sizeof(uint32_t)) {
578 return decode_pfor_vb_interleaved_128_32(in, out);
580 return decode_pfor_vb_interleaved_generic(in, out);
584 __attribute__((target("default")))
585 const unsigned char *decode_pfor_vb_interleaved_128_32(const unsigned char *in, uint32_t *out)
587 return decode_pfor_vb_interleaved_generic<128>(in, out);
590 // Specialized version for SSE2.
591 __attribute__((target("sse2")))
592 const unsigned char *decode_pfor_vb_interleaved_128_32(const unsigned char *in, uint32_t *out)
594 constexpr unsigned BlockSize = 128;
595 using Docid = uint32_t;
597 const unsigned bit_width = *in++ & 0x3f;
598 unsigned num_exceptions = *in++;
600 // Decode the base values.
601 in = decode_bitmap_sse2<BlockSize, /*OrWithExisting=*/false, /*DeltaDecode=*/false>(in, bit_width, out);
603 // Decode exceptions.
604 Docid exceptions[BlockSize];
607 for (unsigned i = 0; i < num_exceptions; ++i) {
608 exceptions[i] = read_le<Docid>(in);
612 for (unsigned i = 0; i < num_exceptions; ++i) {
613 in = read_vb(in, &exceptions[i]);
618 for (unsigned i = 0; i < num_exceptions; ++i) {
619 unsigned idx = *in++;
620 out[idx] |= exceptions[i] << bit_width;
623 delta_decode_sse2<BlockSize>(out);
635 template<unsigned BlockSize, class Docid>
636 const unsigned char *decode_pfor_delta1(const unsigned char *in, unsigned num, bool interleaved, Docid *out)
641 in = read_baseval(in, out++);
643 for (unsigned i = 1; i < num; i += BlockSize, out += BlockSize) {
644 const unsigned num_this_block = std::min<unsigned>(num - i, BlockSize);
645 switch (in[0] >> 6) {
647 if (interleaved && num_this_block == BlockSize) {
648 dprintf("%d+%d: blocktype=%d (for, interleaved), bitwidth=%d\n", i, num_this_block, in[0] >> 6, in[0] & 0x3f);
649 in = decode_for_interleaved<BlockSize>(in, out);
651 dprintf("%d+%d: blocktype=%d (for), bitwidth=%d\n", i, num_this_block, in[0] >> 6, in[0] & 0x3f);
652 in = decode_for(in, num_this_block, out);
655 case BlockType::PFOR_VB:
656 if (interleaved && num_this_block == BlockSize) {
657 dprintf("%d+%d: blocktype=%d (pfor + vb, interleaved), bitwidth=%d\n", i, num_this_block, in[0] >> 6, in[0] & 0x3f);
658 in = decode_pfor_vb_interleaved<BlockSize>(in, out);
660 dprintf("%d+%d: blocktype=%d (pfor + vb), bitwidth=%d\n", i, num_this_block, in[0] >> 6, in[0] & 0x3f);
661 in = decode_pfor_vb<BlockSize>(in, num_this_block, out);
664 case BlockType::PFOR_BITMAP:
665 if (interleaved && num_this_block == BlockSize) {
666 dprintf("%d+%d: blocktype=%d (pfor + bitmap, interleaved), bitwidth=%d\n", i, num_this_block, in[0] >> 6, in[0] & 0x3f);
667 in = decode_pfor_bitmap_interleaved<BlockSize>(in, out);
669 dprintf("%d+%d: blocktype=%d (pfor + bitmap), bitwidth=%d\n", i, num_this_block, in[0] >> 6, in[0] & 0x3f);
670 in = decode_pfor_bitmap(in, num_this_block, out);
673 case BlockType::CONSTANT:
674 dprintf("%d+%d: blocktype=%d (constant), bitwidth=%d\n", i, num_this_block, in[0] >> 6, in[0] & 0x3f);
675 in = decode_constant(in, num_this_block, out);
683 #endif // !defined(_TURBOPFOR_H)