@delali/narsil-react-native 0.3.1-next.154 → 0.3.1-next.156

package/cpp/core/src/keyword/rows.c

@@ -0,0 +1,83 @@
+#include "rows.h"
+
+#include "scratch.h"
+
+#include <stdint.h>
+
+#define INSERTION_SORT_ROWS 16U
+#define UNKNOWN_FIELD_RANK 0x10000U
+
+typedef struct {
+  const uint32_t *source;
+  uint32_t *target;
+} merge_pass;
+
+static uint32_t rank_of(const keyword_row_keys *keys, uint32_t row) {
+  uint16_t field = keys->fields[row];
+  return field < keys->field_count ? keys->name_ranks[field] : UNKNOWN_FIELD_RANK;
+}
+
+static int row_before(const keyword_row_keys *keys, uint32_t lhs, uint32_t rhs) {
+  uint32_t left_doc = keys->doc_ids[lhs];
+  uint32_t right_doc = keys->doc_ids[rhs];
+  if (left_doc != right_doc) { return left_doc < right_doc; }
+  return rank_of(keys, lhs) < rank_of(keys, rhs);
+}
+
+static void insertion_sort(const keyword_row_keys *keys, uint32_t *order, uint32_t begin, uint32_t end) {
+  for (uint32_t place = begin + 1; place < end; place++) {
+    uint32_t row = order[place];
+    uint32_t slot = place;
+    while (slot > begin && row_before(keys, row, order[slot - 1])) {
+      order[slot] = order[slot - 1];
+      slot--;
+    }
+    order[slot] = row;
+  }
+}
+
+static void merge_runs(const keyword_row_keys *keys, const merge_pass *merge, uint32_t begin, uint32_t middle,
+                       uint32_t end) {
+  uint32_t left = begin;
+  uint32_t right = middle;
+  uint32_t out = begin;
+  while (left < middle && right < end) {
+    if (row_before(keys, merge->source[right], merge->source[left])) {
+      merge->target[out++] = merge->source[right++];
+    } else {
+      merge->target[out++] = merge->source[left++];
+    }
+  }
+  while (left < middle) { merge->target[out++] = merge->source[left++]; }
+  while (right < end) { merge->target[out++] = merge->source[right++]; }
+}
+
+static uint32_t smaller(uint64_t value, uint32_t limit) { return value < limit ? (uint32_t)value : limit; }
+
+const uint32_t *keyword_sort_rows(const keyword_row_keys *keys, keyword_scratch *scratch, uint32_t count) {
+  uint32_t *order = scratch->order;
+  if (count <= INSERTION_SORT_ROWS) {
+    insertion_sort(keys, order, 0, count);
+    return order;
+  }
+  for (uint64_t begin = 0; begin < count; begin += INSERTION_SORT_ROWS) {
+    insertion_sort(keys, order, (uint32_t)begin, smaller(begin + INSERTION_SORT_ROWS, count));
+  }
+  merge_pass merge = {order, scratch->order_spare};
+  for (uint64_t width = INSERTION_SORT_ROWS; width < count; width *= 2) {
+    for (uint64_t begin = 0; begin < count; begin += 2 * width) {
+      merge_runs(keys, &merge, (uint32_t)begin, smaller(begin + width, count), smaller(begin + (2 * width), count));
+    }
+    uint32_t *written = merge.target;
+    merge.target = merge.source == order ? order : scratch->order_spare;
+    merge.source = written;
+  }
+  return merge.source;
+}
+
+int keyword_ranks_ascend(const keyword_row_keys *keys, uint32_t begin, uint32_t count) {
+  for (uint32_t row = begin + 1; row < begin + count; row++) {
+    if (rank_of(keys, row) < rank_of(keys, row - 1)) { return 0; }
+  }
+  return 1;
+}

package/cpp/core/src/keyword/rows.h

@@ -0,0 +1,18 @@
+#ifndef NARSIL_KEYWORD_ROWS_H
+#define NARSIL_KEYWORD_ROWS_H
+
+#include "scratch.h"
+
+#include <stdint.h>
+
+typedef struct {
+  const uint32_t *doc_ids;
+  const uint16_t *fields;
+  const uint16_t *name_ranks;
+  uint32_t field_count;
+} keyword_row_keys;
+
+const uint32_t *keyword_sort_rows(const keyword_row_keys *keys, keyword_scratch *scratch, uint32_t count);
+int keyword_ranks_ascend(const keyword_row_keys *keys, uint32_t begin, uint32_t count);
+
+#endif

package/cpp/core/src/keyword/score.c

@@ -0,0 +1,257 @@
+#include "score.h"
+
+#include "pass.h"
+#include "rows.h"
+#include "scratch.h"
+#include "select.h"
+
+#include "../math/fdlibm.h"
+
+#include "../../include/narsil_keyword.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+#define IDF_HALF_DOCUMENT 0.5
+
+typedef struct {
+  int member_mode;
+  double idf;
+  int has_term;
+  uint32_t term;
+  double factor;
+  double partial_factor;
+} keyword_run;
+
+typedef struct {
+  const keyword_pass *pass;
+  keyword_run *run;
+  const keyword_row_keys *keys;
+  const keyword_rows *rows;
+} list_scan;
+
+typedef struct {
+  const uint32_t *order;
+  uint32_t begin;
+  uint32_t end;
+  uint32_t ordinal;
+} row_run;
+
+double keyword_idf(double document_frequency, double total_documents) {
+  if (total_documents == 0) { return 0; }
+  double rest = (total_documents - document_frequency) + IDF_HALF_DOCUMENT;
+  return fdlibm_log((rest / (document_frequency + IDF_HALF_DOCUMENT)) + 1);
+}
+
+void keyword_list_rows(const keyword_pass *pass, uint32_t list, keyword_rows *rows) {
+  const narsil_keyword_request *request = pass->request;
+  if ((keyword_list_flags(request, list) & NARSIL_KEYWORD_LIST_FROM_ROWS) != 0) {
+    rows->doc_ids = request->row_doc_ids;
+    rows->fields = request->row_fields;
+    rows->narrow_frequencies = NULL;
+    rows->wide_frequencies = request->row_frequencies;
+  } else {
+    rows->doc_ids = request->pool_doc_ids;
+    rows->fields = request->pool_fields;
+    rows->narrow_frequencies = request->pool_frequencies;
+    rows->wide_frequencies = NULL;
+  }
+}
+
+void keyword_list_keys(const keyword_pass *pass, uint32_t list, keyword_row_keys *keys) {
+  keyword_rows rows;
+  keyword_list_rows(pass, list, &rows);
+  keys->doc_ids = rows.doc_ids;
+  keys->fields = rows.fields;
+  keys->name_ranks = pass->request->name_ranks;
+  keys->field_count = pass->field_count;
+}
+
+static void touch(const keyword_pass *pass, uint32_t ordinal) {
+  keyword_scratch *scratch = pass->scratch;
+  if (scratch->stamps[ordinal] == scratch->generation) { return; }
+  scratch->stamps[ordinal] = scratch->generation;
+  scratch->scores[ordinal] = 0;
+  if (pass->tracks_coverage) {
+    scratch->covered[ordinal] = 0;
+    scratch->last_term[ordinal] = 0;
+  }
+  scratch->touched[scratch->touched_count++] = ordinal;
+}
+
+static void cover(const keyword_pass *pass, uint32_t ordinal, uint32_t term) {
+  if (!pass->tracks_coverage) { return; }
+  keyword_scratch *scratch = pass->scratch;
+  if (scratch->last_term[ordinal] == term + 1) { return; }
+  scratch->last_term[ordinal] = term + 1;
+  scratch->covered[ordinal]++;
+}
+
+static void score_row(const list_scan *scan, uint32_t row, uint32_t ordinal) {
+  const keyword_pass *pass = scan->pass;
+  uint32_t field = scan->rows->fields[row];
+  if (!keyword_searchable(pass, field)) { return; }
+  touch(pass, ordinal);
+  pass->scratch->scores[ordinal] +=
+      keyword_row_score(pass, scan->run->idf, keyword_frequency(scan->rows, row), field, ordinal);
+  if (scan->run->has_term) { cover(pass, ordinal, scan->run->term); }
+}
+
+static void score_members(const list_scan *scan, const row_run *rows) {
+  const keyword_pass *pass = scan->pass;
+  const keyword_run *run = scan->run;
+  const uint8_t *partial_marks = pass->request->partial_marks;
+  uint32_t ordinal = rows->ordinal;
+  double sum = 0;
+  int any = 0;
+  for (uint32_t place = rows->begin; place < rows->end; place++) {
+    uint32_t row = rows->order[place];
+    uint32_t field = scan->rows->fields[row];
+    if (!keyword_searchable(pass, field)) { continue; }
+    double factor = partial_marks[field] == 1 ? run->partial_factor : run->factor;
+    if (!(factor > 0)) { continue; }
+    sum += keyword_row_score(pass, run->idf, keyword_frequency(scan->rows, row), field, ordinal) * factor;
+    any = 1;
+  }
+  if (!any) { return; }
+  keyword_scratch *scratch = pass->scratch;
+  if (scratch->group_stamps[ordinal] != scratch->group_generation) {
+    scratch->group_stamps[ordinal] = scratch->group_generation;
+    scratch->group_best[ordinal] = sum;
+    scratch->group_touched[scratch->group_touched_count++] = ordinal;
+  } else if (sum > scratch->group_best[ordinal]) {
+    scratch->group_best[ordinal] = sum;
+  }
+}
+
+static void score_run(const list_scan *scan, const row_run *rows) {
+  if (scan->run->member_mode) {
+    score_members(scan, rows);
+    return;
+  }
+  for (uint32_t place = rows->begin; place < rows->end; place++) { score_row(scan, rows->order[place], rows->ordinal); }
+}
+
+static void score_unordered_list(const list_scan *scan, uint32_t begin, uint32_t length) {
+  keyword_scratch *scratch = scan->pass->scratch;
+  const uint32_t *doc_ids = scan->keys->doc_ids;
+  for (uint32_t place = 0; place < length; place++) { scratch->order[place] = begin + place; }
+  const uint32_t *sorted = keyword_sort_rows(scan->keys, scratch, length);
+  uint32_t place = 0;
+  while (place < length) {
+    uint32_t ordinal = doc_ids[sorted[place]];
+    uint32_t end = place + 1;
+    while (end < length && doc_ids[sorted[end]] == ordinal) { end++; }
+    if (keyword_scorable(scan->pass, ordinal)) {
+      row_run rows = {sorted, place, end, ordinal};
+      score_run(scan, &rows);
+    }
+    place = end;
+  }
+}
+
+const uint32_t *keyword_rank_ordered_run(const keyword_pass *pass, const keyword_row_keys *keys, uint32_t begin,
+                                         uint32_t count) {
+  keyword_scratch *scratch = pass->scratch;
+  uint32_t *rows = scratch->order;
+  for (uint32_t row = 0; row < count; row++) { rows[row] = begin + row; }
+  if (count > 1 && !keyword_ranks_ascend(keys, begin, count)) { return keyword_sort_rows(keys, scratch, count); }
+  return rows;
+}
+
+static void score_ordered_list(const list_scan *scan, uint32_t begin, uint32_t length) {
+  const uint32_t *doc_ids = scan->keys->doc_ids;
+  uint32_t end = begin + length;
+  uint32_t place = begin;
+  while (place < end) {
+    uint32_t ordinal = doc_ids[place];
+    uint32_t run_end = place + 1;
+    while (run_end < end && doc_ids[run_end] == ordinal) { run_end++; }
+    if (keyword_scorable(scan->pass, ordinal)) {
+      uint32_t count = run_end - place;
+      if (count == 1 && !scan->run->member_mode) {
+        score_row(scan, place, ordinal);
+      } else {
+        row_run rows = {keyword_rank_ordered_run(scan->pass, scan->keys, place, count), 0, count, ordinal};
+        score_run(scan, &rows);
+      }
+    }
+    place = run_end;
+  }
+}
+
+static void score_list(const keyword_pass *pass, keyword_run *run, uint32_t list) {
+  const narsil_keyword_request *request = pass->request;
+  keyword_rows rows;
+  keyword_row_keys keys;
+  keyword_list_rows(pass, list, &rows);
+  keyword_list_keys(pass, list, &keys);
+  run->factor = keyword_list_value(request, list, NARSIL_KEYWORD_LIST_FACTOR);
+  run->partial_factor = keyword_list_value(request, list, NARSIL_KEYWORD_LIST_PARTIAL_FACTOR);
+  list_scan scan = {pass, run, &keys, &rows};
+  uint32_t begin = keyword_list_start(request, list);
+  uint32_t length = keyword_list_length(request, list);
+  if ((keyword_list_flags(request, list) & NARSIL_KEYWORD_LIST_ORDERED) == 0) {
+    score_unordered_list(&scan, begin, length);
+  } else {
+    score_ordered_list(&scan, begin, length);
+  }
+}
+
+static void finish_group(const keyword_pass *pass, uint32_t term) {
+  keyword_scratch *scratch = pass->scratch;
+  for (uint32_t index = 0; index < scratch->group_touched_count; index++) {
+    uint32_t ordinal = scratch->group_touched[index];
+    touch(pass, ordinal);
+    scratch->scores[ordinal] += scratch->group_best[ordinal];
+    cover(pass, ordinal, term);
+  }
+}
+
+static uint32_t slot_word(const narsil_keyword_request *request, uint32_t slot, uint32_t word) {
+  return request->slots[((size_t)slot * NARSIL_KEYWORD_SLOT_STRIDE) + word];
+}
+
+static double list_idf(const narsil_keyword_request *request, uint32_t list) {
+  return keyword_idf(keyword_list_value(request, list, NARSIL_KEYWORD_LIST_DOCUMENT_FREQUENCY),
+                     request->total_documents);
+}
+
+uint32_t keyword_score_every_slot(const keyword_pass *pass) {
+  const narsil_keyword_request *request = pass->request;
+  double total_documents = request->total_documents;
+  keyword_begin(pass->scratch);
+  uint32_t list_from = 0;
+  uint32_t value_from = 0;
+  for (uint32_t slot = 0; slot < request->slot_count; slot++) {
+    uint32_t kind = slot_word(request, slot, NARSIL_KEYWORD_SLOT_KIND);
+    uint32_t term = slot_word(request, slot, NARSIL_KEYWORD_SLOT_TERM);
+    uint32_t list_end = slot_word(request, slot, NARSIL_KEYWORD_SLOT_LIST_END);
+    uint32_t value_end = slot_word(request, slot, NARSIL_KEYWORD_SLOT_VALUE_END);
+    keyword_run run = {0, 0, 0, term, 0, 0};
+    if (kind == NARSIL_KEYWORD_TERM_SLOT) {
+      run.has_term = 1;
+      for (uint32_t list = list_from; list < list_end; list++) {
+        run.idf = list_idf(request, list);
+        score_list(pass, &run, list);
+      }
+    } else if (kind == NARSIL_KEYWORD_GROUP_SLOT) {
+      run.member_mode = 1;
+      run.has_term = 1;
+      run.idf = keyword_idf(request->slot_values[value_from], total_documents);
+      keyword_begin_group(pass->scratch);
+      for (uint32_t list = list_from; list < list_end; list++) { score_list(pass, &run, list); }
+      finish_group(pass, term);
+    } else {
+      double idf = 0;
+      for (uint32_t value = value_from; value < value_end; value++) {
+        idf += keyword_idf(request->slot_values[value], total_documents);
+      }
+      run.idf = idf;
+      for (uint32_t list = list_from; list < list_end; list++) { score_list(pass, &run, list); }
+    }
+    list_from = list_end;
+    value_from = value_end;
+  }
+  return keyword_select_kept(pass);
+}

package/cpp/core/src/keyword/score.h

@@ -0,0 +1,17 @@
+#ifndef NARSIL_KEYWORD_SCORE_H
+#define NARSIL_KEYWORD_SCORE_H
+
+#include "pass.h"
+#include "rows.h"
+
+#include <stdint.h>
+
+#define KEYWORD_NOT_PRUNED UINT32_MAX
+
+void keyword_list_keys(const keyword_pass *pass, uint32_t list, keyword_row_keys *keys);
+const uint32_t *keyword_rank_ordered_run(const keyword_pass *pass, const keyword_row_keys *keys, uint32_t begin,
+                                         uint32_t count);
+uint32_t keyword_score_every_slot(const keyword_pass *pass);
+uint32_t keyword_score_pruned(const keyword_pass *pass);
+
+#endif

package/cpp/core/src/keyword/scratch.c

@@ -0,0 +1,226 @@
+#include "scratch.h"
+
+#include "../internal.h"
+
+#include "../../include/narsil_core.h"
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define FIRST_ORDER_CAPACITY 256U
+#define FIRST_SELECTION_CAPACITY 16U
+#define FIRST_LIST_CAPACITY 16U
+#define MAX_GENERATION INT32_MAX
+#define BITS_PER_WORD 32U
+#define BITSETS_PER_SCRATCH 3U
+#define TOUCHED_SPARE_ENTRIES 1U
+
+static void *allocation(size_t count, size_t size) {
+  if (count == 0 || count > SIZE_MAX / size) { return NULL; }
+  return malloc(count * size);
+}
+
+static void *zeroed_allocation(size_t count, size_t size) {
+  if (count == 0) { return NULL; }
+  return calloc(count, size);
+}
+
+void keyword_scratch_release(keyword_scratch *scratch) {
+  free(scratch->scores);
+  free(scratch->stamps);
+  free(scratch->touched);
+  free(scratch->scorable);
+  free(scratch->seen_bits);
+  free(scratch->counted_bits);
+  free(scratch->covered);
+  free(scratch->last_term);
+  free(scratch->group_best);
+  free(scratch->group_stamps);
+  free(scratch->group_touched);
+  free(scratch->order);
+  free(scratch->order_spare);
+  free(scratch->selection);
+  free(scratch->list_order);
+  free(scratch->list_bounds);
+  free(scratch->list_idfs);
+  free(scratch->remaining_bounds);
+  memset(scratch, 0, sizeof *scratch);
+}
+
+size_t keyword_scratch_bytes(const keyword_scratch *scratch) {
+  size_t per_ordinal = sizeof(double) + sizeof(int32_t) + sizeof(uint32_t);
+  size_t per_covered = 2 * sizeof(uint32_t);
+  size_t per_group = sizeof(double) + sizeof(int32_t) + sizeof(uint32_t);
+  size_t per_list = sizeof(uint32_t) + (3 * sizeof(double));
+  size_t remaining_end = scratch->list_capacity > 0 ? sizeof(double) : 0;
+  size_t bitset_words = (size_t)(scratch->capacity / BITS_PER_WORD) + 1;
+  size_t ordinal_extras =
+      scratch->capacity > 0 ? sizeof(uint32_t) * ((BITSETS_PER_SCRATCH * bitset_words) + TOUCHED_SPARE_ENTRIES) : 0;
+  return ((size_t)scratch->capacity * per_ordinal) + ordinal_extras +
+         ((size_t)scratch->coverage_capacity * per_covered) + ((size_t)scratch->group_capacity * per_group) +
+         ((size_t)scratch->order_capacity * 2 * sizeof(uint32_t)) +
+         ((size_t)scratch->selection_capacity * sizeof(double)) + ((size_t)scratch->list_capacity * per_list) +
+         remaining_end;
+}
+
+static narsil_status reserve_ordinals(keyword_scratch *scratch, uint32_t capacity) {
+  if (capacity <= scratch->capacity) { return NARSIL_OK; }
+  size_t bitset_words = (size_t)(capacity / BITS_PER_WORD) + 1;
+  double *scores = zeroed_allocation(capacity, sizeof *scores);
+  int32_t *stamps = zeroed_allocation(capacity, sizeof *stamps);
+  uint32_t *touched = allocation((size_t)capacity + TOUCHED_SPARE_ENTRIES, sizeof *touched);
+  uint32_t *scorable = allocation(bitset_words, sizeof *scorable);
+  uint32_t *seen_bits = allocation(bitset_words, sizeof *seen_bits);
+  uint32_t *counted_bits = allocation(bitset_words, sizeof *counted_bits);
+  if (scores == NULL || stamps == NULL || touched == NULL || scorable == NULL || seen_bits == NULL ||
+      counted_bits == NULL) {
+    free(scores);
+    free(stamps);
+    free(touched);
+    free(scorable);
+    free(seen_bits);
+    free(counted_bits);
+    return NARSIL_OUT_OF_MEMORY;
+  }
+  free(scratch->scores);
+  free(scratch->stamps);
+  free(scratch->touched);
+  free(scratch->scorable);
+  free(scratch->seen_bits);
+  free(scratch->counted_bits);
+  scratch->scores = scores;
+  scratch->stamps = stamps;
+  scratch->touched = touched;
+  scratch->scorable = scorable;
+  scratch->seen_bits = seen_bits;
+  scratch->counted_bits = counted_bits;
+  scratch->capacity = capacity;
+  scratch->generation = 0;
+  return NARSIL_OK;
+}
+
+static narsil_status reserve_coverage(keyword_scratch *scratch, uint32_t capacity) {
+  if (capacity <= scratch->coverage_capacity) { return NARSIL_OK; }
+  uint32_t *covered = allocation(capacity, sizeof *covered);
+  uint32_t *last_term = allocation(capacity, sizeof *last_term);
+  if (covered == NULL || last_term == NULL) {
+    free(covered);
+    free(last_term);
+    return NARSIL_OUT_OF_MEMORY;
+  }
+  free(scratch->covered);
+  free(scratch->last_term);
+  scratch->covered = covered;
+  scratch->last_term = last_term;
+  scratch->coverage_capacity = capacity;
+  return NARSIL_OK;
+}
+
+static narsil_status reserve_groups(keyword_scratch *scratch, uint32_t capacity) {
+  if (capacity <= scratch->group_capacity) { return NARSIL_OK; }
+  double *best = allocation(capacity, sizeof *best);
+  int32_t *stamps = zeroed_allocation(capacity, sizeof *stamps);
+  uint32_t *touched = allocation(capacity, sizeof *touched);
+  if (best == NULL || stamps == NULL || touched == NULL) {
+    free(best);
+    free(stamps);
+    free(touched);
+    return NARSIL_OUT_OF_MEMORY;
+  }
+  free(scratch->group_best);
+  free(scratch->group_stamps);
+  free(scratch->group_touched);
+  scratch->group_best = best;
+  scratch->group_stamps = stamps;
+  scratch->group_touched = touched;
+  scratch->group_capacity = capacity;
+  scratch->group_generation = 0;
+  return NARSIL_OK;
+}
+
+static narsil_status reserve_order(keyword_scratch *scratch, uint32_t needed) {
+  if (needed <= scratch->order_capacity) { return NARSIL_OK; }
+  uint32_t capacity = grown_capacity(FIRST_ORDER_CAPACITY, needed);
+  uint32_t *order = allocation(capacity, sizeof *order);
+  uint32_t *spare = allocation(capacity, sizeof *spare);
+  if (order == NULL || spare == NULL) {
+    free(order);
+    free(spare);
+    return NARSIL_OUT_OF_MEMORY;
+  }
+  free(scratch->order);
+  free(scratch->order_spare);
+  scratch->order = order;
+  scratch->order_spare = spare;
+  scratch->order_capacity = capacity;
+  return NARSIL_OK;
+}
+
+static narsil_status reserve_selection(keyword_scratch *scratch, uint32_t needed) {
+  if (needed <= scratch->selection_capacity) { return NARSIL_OK; }
+  uint32_t capacity = grown_capacity(FIRST_SELECTION_CAPACITY, needed);
+  double *selection = allocation(capacity, sizeof *selection);
+  if (selection == NULL) { return NARSIL_OUT_OF_MEMORY; }
+  free(scratch->selection);
+  scratch->selection = selection;
+  scratch->selection_capacity = capacity;
+  return NARSIL_OK;
+}
+
+static narsil_status reserve_lists(keyword_scratch *scratch, uint32_t needed) {
+  if (needed <= scratch->list_capacity) { return NARSIL_OK; }
+  uint32_t capacity = grown_capacity(FIRST_LIST_CAPACITY, needed);
+  uint32_t *order = allocation(capacity, sizeof *order);
+  double *bounds = allocation(capacity, sizeof *bounds);
+  double *idfs = allocation(capacity, sizeof *idfs);
+  double *remaining = allocation((size_t)capacity + 1, sizeof *remaining);
+  if (order == NULL || bounds == NULL || idfs == NULL || remaining == NULL) {
+    free(order);
+    free(bounds);
+    free(idfs);
+    free(remaining);
+    return NARSIL_OUT_OF_MEMORY;
+  }
+  free(scratch->list_order);
+  free(scratch->list_bounds);
+  free(scratch->list_idfs);
+  free(scratch->remaining_bounds);
+  scratch->list_order = order;
+  scratch->list_bounds = bounds;
+  scratch->list_idfs = idfs;
+  scratch->remaining_bounds = remaining;
+  scratch->list_capacity = capacity;
+  return NARSIL_OK;
+}
+
+narsil_status keyword_reserve(keyword_scratch *scratch, const keyword_needs *needs) {
+  narsil_status status = reserve_ordinals(scratch, needs->capacity);
+  if (status == NARSIL_OK && needs->coverage) { status = reserve_coverage(scratch, needs->capacity); }
+  if (status == NARSIL_OK && needs->groups) { status = reserve_groups(scratch, needs->capacity); }
+  if (status == NARSIL_OK) { status = reserve_order(scratch, needs->order); }
+  if (status == NARSIL_OK) { status = reserve_selection(scratch, needs->selection); }
+  if (status == NARSIL_OK) { status = reserve_lists(scratch, needs->lists); }
+  return status;
+}
+
+void keyword_begin(keyword_scratch *scratch) {
+  if (scratch->generation >= MAX_GENERATION) {
+    if (scratch->capacity > 0) { memset(scratch->stamps, 0, (size_t)scratch->capacity * sizeof *scratch->stamps); }
+    scratch->generation = 0;
+  }
+  scratch->generation++;
+  scratch->touched_count = 0;
+}
+
+void keyword_begin_group(keyword_scratch *scratch) {
+  if (scratch->group_generation >= MAX_GENERATION) {
+    if (scratch->group_capacity > 0) {
+      memset(scratch->group_stamps, 0, (size_t)scratch->group_capacity * sizeof *scratch->group_stamps);
+    }
+    scratch->group_generation = 0;
+  }
+  scratch->group_generation++;
+  scratch->group_touched_count = 0;
+}

package/cpp/core/src/keyword/scratch.h

@@ -0,0 +1,55 @@
+#ifndef NARSIL_KEYWORD_SCRATCH_H
+#define NARSIL_KEYWORD_SCRATCH_H
+
+#include "../../include/narsil_core.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+typedef struct {
+  double *scores;
+  int32_t *stamps;
+  uint32_t *touched;
+  uint32_t *scorable;
+  uint32_t *seen_bits;
+  uint32_t *counted_bits;
+  uint32_t capacity;
+  int32_t generation;
+  uint32_t touched_count;
+  uint32_t *covered;
+  uint32_t *last_term;
+  uint32_t coverage_capacity;
+  double *group_best;
+  int32_t *group_stamps;
+  uint32_t *group_touched;
+  uint32_t group_capacity;
+  int32_t group_generation;
+  uint32_t group_touched_count;
+  uint32_t *order;
+  uint32_t *order_spare;
+  uint32_t order_capacity;
+  double *selection;
+  uint32_t selection_capacity;
+  uint32_t *list_order;
+  double *list_bounds;
+  double *list_idfs;
+  double *remaining_bounds;
+  uint32_t list_capacity;
+} keyword_scratch;
+
+typedef struct {
+  uint32_t capacity;
+  int coverage;
+  int groups;
+  uint32_t order;
+  uint32_t selection;
+  uint32_t lists;
+} keyword_needs;
+
+void keyword_scratch_release(keyword_scratch *scratch);
+size_t keyword_scratch_bytes(const keyword_scratch *scratch);
+narsil_status keyword_reserve(keyword_scratch *scratch, const keyword_needs *needs);
+void keyword_begin(keyword_scratch *scratch);
+void keyword_begin_group(keyword_scratch *scratch);
+
+#endif