@delali/narsil-react-native 0.0.0-stage → 0.3.1-next.151

package/cpp/core/src/locks.c

@@ -0,0 +1,168 @@
+#include "internal.h"
+
+#include "../include/narsil_core.h"
+
+#include <stdatomic.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <sched.h>
+#endif
+
+#define LOCK_SPIN_ITERATIONS 128
+#define LIST_COUNT_WORDS 1
+#define LOCK_FREE 0
+#define LOCK_HELD_ALONE (-1)
+
+static inline void yield_thread(void) {
+#ifdef _WIN32
+  SwitchToThread();
+#else
+  sched_yield();
+#endif
+}
+
+static inline void wait_for_the_lock(uint32_t *waits) {
+  if (*waits < LOCK_SPIN_ITERATIONS) {
+    *waits += 1;
+    return;
+  }
+  yield_thread();
+}
+
+static inline uint32_t held_index(uint32_t thread_slot, uint32_t kind) {
+  return (thread_slot * NARSIL_HELD_WORDS_PER_THREAD) + kind;
+}
+
+void graph_lock_shared(const narsil_graph *graph, uint32_t thread_slot) {
+  _Atomic(int32_t) *lock = atomic_word(graph->header, NARSIL_GRAPH_WORD_LOCK);
+  _Atomic(int32_t) *writers_waiting = atomic_word(graph->header, NARSIL_GRAPH_WORD_WRITERS_WAITING);
+  uint32_t waits = 0;
+  for (;;) {
+    int32_t seen = atomic_load(lock);
+    if (seen >= 0 && atomic_load(writers_waiting) == 0) {
+      if (atomic_compare_exchange_strong(lock, &seen, seen + 1)) {
+        atomic_store(atomic_word(graph->held_locks, held_index(thread_slot, NARSIL_HELD_WORD_GRAPH)), 1);
+        return;
+      }
+      continue;
+    }
+    wait_for_the_lock(&waits);
+  }
+}
+
+void graph_unlock_shared(const narsil_graph *graph, uint32_t thread_slot) {
+  atomic_store(atomic_word(graph->held_locks, held_index(thread_slot, NARSIL_HELD_WORD_GRAPH)), 0);
+  atomic_fetch_sub(atomic_word(graph->header, NARSIL_GRAPH_WORD_LOCK), 1);
+}
+
+void node_lock(const walk_context *context, int32_t ordinal) {
+  const narsil_graph *graph = context->graph;
+  uint32_t thread_slot = context->thread_slot;
+  _Atomic(int32_t) *word = atomic_word(graph->locks, (uint32_t)ordinal);
+  uint32_t waits = 0;
+  for (;;) {
+    int32_t seen = atomic_load(word);
+    if ((seen & NODE_WRITE_HELD) == 0) {
+      int32_t claimed = seen | NODE_WRITE_HELD;
+      if (atomic_compare_exchange_strong(word, &seen, claimed)) {
+        atomic_store(atomic_word(graph->held_locks, held_index(thread_slot, NARSIL_HELD_WORD_NODE_VALUE)), claimed);
+        atomic_store(atomic_word(graph->held_locks, held_index(thread_slot, NARSIL_HELD_WORD_NODE)), ordinal + 1);
+        return;
+      }
+      continue;
+    }
+    wait_for_the_lock(&waits);
+  }
+}
+
+void node_unlock(const walk_context *context, int32_t ordinal) {
+  const narsil_graph *graph = context->graph;
+  _Atomic(int32_t) *word = atomic_word(graph->locks, (uint32_t)ordinal);
+  uint32_t seen = (uint32_t)atomic_load(word);
+  uint32_t released = (seen & ~(uint32_t)(NODE_WRITE_HELD | NODE_WRITER_WAITING)) + NODE_VERSION_STEP;
+  int32_t previous = atomic_exchange(word, (int32_t)released);
+  if ((previous & NODE_WRITER_WAITING) != 0 && graph->wake != NULL) { graph->wake(graph->wake_context, ordinal); }
+  atomic_store(atomic_word(graph->held_locks, held_index(context->thread_slot, NARSIL_HELD_WORD_NODE)), 0);
+}
+
+void entry_lock(const walk_context *context) {
+  const narsil_graph *graph = context->graph;
+  _Atomic(int32_t) *lock = atomic_word(graph->header, NARSIL_GRAPH_WORD_ENTRY_LOCK);
+  uint32_t waits = 0;
+  for (;;) {
+    int32_t expected = LOCK_FREE;
+    if (atomic_compare_exchange_strong(lock, &expected, LOCK_HELD_ALONE)) {
+      atomic_store(atomic_word(graph->held_locks, held_index(context->thread_slot, NARSIL_HELD_WORD_ENTRY)), 1);
+      return;
+    }
+    wait_for_the_lock(&waits);
+  }
+}
+
+void entry_unlock(const walk_context *context) {
+  const narsil_graph *graph = context->graph;
+  atomic_store(atomic_word(graph->held_locks, held_index(context->thread_slot, NARSIL_HELD_WORD_ENTRY)), 0);
+  atomic_store(atomic_word(graph->header, NARSIL_GRAPH_WORD_ENTRY_LOCK), LOCK_FREE);
+  if (graph->wake != NULL) { graph->wake(graph->wake_context, NARSIL_WAKE_ENTRY_LOCK); }
+}
+
+int32_t node_top_layer(const walk_context *context, int32_t ordinal) {
+  if (ordinal < 0 || (uint32_t)ordinal >= context->slots) { return NO_NODE; }
+  return (int32_t)atomic_load(atomic_byte(context->graph->node_levels, (uint32_t)ordinal)) - 1;
+}
+
+uint32_t list_limit(const narsil_graph *graph, int32_t layer) {
+  int32_t limit = load_word(graph->header, layer == 0 ? NARSIL_GRAPH_WORD_MMAX0 : NARSIL_GRAPH_WORD_M);
+  return limit <= 0 ? 0 : (uint32_t)limit;
+}
+
+int32_t *list_at(const walk_context *context, node_layer position, uint32_t *capacity) {
+  const narsil_graph *graph = context->graph;
+  *capacity = 0;
+  int32_t level = node_top_layer(context, position.ordinal);
+  if (level < 0 || position.layer < 0 || position.layer > level) { return NULL; }
+  if (graph->level0 == NULL || graph->upper == NULL || graph->upper_base == NULL) { return NULL; }
+  uint32_t limit = list_limit(graph, position.layer);
+  if (limit == 0 || limit >= MAX_NEIGHBOURS_PER_LIST) { return NULL; }
+  uint64_t stride = (uint64_t)limit + NARSIL_LIST_WORDS_OVER_NEIGHBOURS;
+  if (position.layer == 0) {
+    *capacity = (uint32_t)(stride - LIST_COUNT_WORDS);
+    return graph->level0 + ((size_t)position.ordinal * stride);
+  }
+  int32_t base = graph->upper_base[position.ordinal];
+  if (base <= 0) { return NULL; }
+  uint64_t start = (uint64_t)(base - 1) + ((uint64_t)(position.layer - 1) * stride);
+  int32_t upper_used = load_word(graph->header, NARSIL_GRAPH_WORD_UPPER_USED);
+  if (upper_used < 0 || start + stride > (uint64_t)upper_used) { return NULL; }
+  *capacity = (uint32_t)(stride - LIST_COUNT_WORDS);
+  return graph->upper + start;
+}
+
+uint32_t read_neighbours(const walk_context *context, node_layer position, int32_t *out) {
+  const narsil_graph *graph = context->graph;
+  _Atomic(int32_t) *word = atomic_word(graph->locks, (uint32_t)position.ordinal);
+  _Atomic(int32_t) *fence = atomic_word(context->fence, 0);
+  uint32_t waits = 0;
+  for (;;) {
+    int32_t before = atomic_load(word);
+    if ((before & NODE_WRITE_HELD) != 0) {
+      wait_for_the_lock(&waits);
+      continue;
+    }
+    uint32_t capacity = 0;
+    const int32_t *list = list_at(context, position, &capacity);
+    uint32_t count = 0;
+    if (list != NULL) {
+      int32_t stored = list[0];
+      count = stored < 0 ? 0 : (uint32_t)stored;
+      if (count > capacity) { count = capacity; }
+      for (uint32_t i = 0; i < count; i++) { out[i] = list[i + 1]; }
+    }
+    atomic_fetch_add(fence, 0);
+    if (atomic_load(word) == before) { return count; }
+  }
+}

package/cpp/core/src/nearest_links.c

@@ -0,0 +1,147 @@
+#include "internal.h"
+
+#include "../include/narsil_core.h"
+
+#include <stdatomic.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#define NEAREST_LINK_FALLBACK_HOSTS 4U
+#define NEAREST_NOT_YET_FOUND (-2)
+
+typedef struct {
+  const walk_context *context;
+  int32_t *nearest;
+} nearest_pass;
+
+typedef struct {
+  int32_t host;
+  int32_t node;
+} back_link;
+
+static int nearer(scored_node first, scored_node second) {
+  return first.distance < second.distance || (first.distance == second.distance && first.ordinal < second.ordinal);
+}
+
+static int32_t *base_list(const walk_context *context, int32_t ordinal, uint32_t *count) {
+  uint32_t capacity = 0;
+  node_layer base = {ordinal, 0};
+  int32_t *list = list_at(context, base, &capacity);
+  *count = list == NULL ? 0 : stored_count(list, capacity);
+  return list;
+}
+
+static int32_t nearest_in_list(const nearest_pass *pass, int32_t ordinal) {
+  if (pass->nearest[ordinal] != NEAREST_NOT_YET_FOUND) { return pass->nearest[ordinal]; }
+  const walk_context *context = pass->context;
+  uint32_t count = 0;
+  const int32_t *list = base_list(context, ordinal, &count);
+  scored_node best = {NO_NODE, 0};
+  for (uint32_t i = 1; i <= count; i++) {
+    int32_t neighbour = list[i];
+    if (neighbour == ordinal || !is_live(context, neighbour)) { continue; }
+    scored_node scored = {neighbour, pair_distance(context, ordinal, neighbour)};
+    if (best.ordinal == NO_NODE || nearer(scored, best)) { best = scored; }
+  }
+  pass->nearest[ordinal] = best.ordinal;
+  return best.ordinal;
+}
+
+static uint32_t fallback_hosts_for(const nearest_pass *pass, back_link first, int32_t *hosts) {
+  int32_t ordinal = first.node;
+  int32_t nearest = first.host;
+  const walk_context *context = pass->context;
+  scored_node around[NEAREST_LINK_FALLBACK_HOSTS];
+  uint32_t kept = 0;
+  uint32_t count = 0;
+  const int32_t *list = base_list(context, nearest, &count);
+  for (uint32_t i = 1; i <= count; i++) {
+    int32_t neighbour = list[i];
+    if (neighbour == ordinal || !is_live(context, neighbour)) { continue; }
+    scored_node scored = {neighbour, pair_distance(context, ordinal, neighbour)};
+    if (kept == NEAREST_LINK_FALLBACK_HOSTS && !nearer(scored, around[kept - 1])) { continue; }
+    uint32_t slot = kept < NEAREST_LINK_FALLBACK_HOSTS ? kept++ : kept - 1;
+    while (slot > 0 && nearer(scored, around[slot - 1])) {
+      around[slot] = around[slot - 1];
+      slot -= 1;
+    }
+    around[slot] = scored;
+  }
+  for (uint32_t i = 0; i < kept; i++) { hosts[i] = around[i].ordinal; }
+  return kept;
+}
+
+static int64_t replaceable_slot(const nearest_pass *pass, int32_t host, const int32_t *list, uint32_t count) {
+  const walk_context *context = pass->context;
+  int64_t farthest = -1;
+  scored_node farthest_node = {NO_NODE, 0};
+  for (uint32_t i = 1; i <= count; i++) {
+    int32_t neighbour = list[i];
+    if (incoming_count(context, neighbour) < 2) { continue; }
+    if (is_live(context, neighbour) && nearest_in_list(pass, neighbour) == host) { continue; }
+    scored_node scored = {neighbour, pair_distance(context, host, neighbour)};
+    if (farthest == -1 || nearer(farthest_node, scored)) {
+      farthest = i;
+      farthest_node = scored;
+    }
+  }
+  return farthest;
+}
+
+static int link_from(const nearest_pass *pass, back_link link) {
+  const walk_context *context = pass->context;
+  int32_t host = link.host;
+  int32_t ordinal = link.node;
+  node_lock(context, host);
+  uint32_t count = 0;
+  int32_t *list = base_list(context, host, &count);
+  int linked = 0;
+  if (list != NULL) {
+    for (uint32_t i = 1; i <= count && !linked; i++) { linked = list[i] == ordinal; }
+    if (!linked && count < list_limit(context->graph, 0)) {
+      list[count + 1] = ordinal;
+      list[0] = (int32_t)(count + 1);
+      note_linked(context, ordinal);
+      pass->nearest[host] = NEAREST_NOT_YET_FOUND;
+      linked = 1;
+    }
+    int64_t slot = linked ? -1 : replaceable_slot(pass, host, list, count);
+    if (slot != -1) {
+      int32_t replaced = list[slot];
+      list[slot] = ordinal;
+      note_unlinked(context, replaced);
+      note_linked(context, ordinal);
+      pass->nearest[host] = NEAREST_NOT_YET_FOUND;
+      linked = 1;
+    }
+  }
+  node_unlock(context, host);
+  return linked;
+}
+
+narsil_status link_from_nearest(const walk_context *context) {
+  size_t slots = context->slots;
+  nearest_pass pass = {context, malloc((slots == 0 ? 1 : slots) * sizeof(int32_t))};
+  if (pass.nearest == NULL) { return NARSIL_OUT_OF_MEMORY; }
+  for (size_t i = 0; i < slots; i++) { pass.nearest[i] = NEAREST_NOT_YET_FOUND; }
+  int32_t hosts[NEAREST_LINK_FALLBACK_HOSTS];
+  for (uint32_t ordinal = 0; ordinal < slots; ordinal++) {
+    _Atomic(uint8_t) *due = atomic_byte(context->graph->nearest_link_due, ordinal);
+    if (atomic_load(due) != 1) { continue; }
+    atomic_store(due, 0);
+    int32_t node = (int32_t)ordinal;
+    if (!is_live(context, node)) { continue; }
+    int32_t nearest = nearest_in_list(&pass, node);
+    if (nearest == NO_NODE) { continue; }
+    back_link first = {nearest, node};
+    if (link_from(&pass, first)) { continue; }
+    uint32_t host_count = fallback_hosts_for(&pass, first, hosts);
+    for (uint32_t i = 0; i < host_count; i++) {
+      back_link link = {hosts[i], node};
+      if (link_from(&pass, link)) { break; }
+    }
+  }
+  free(pass.nearest);
+  return NARSIL_OK;
+}

package/cpp/core/src/place.c

@@ -0,0 +1,215 @@
+#include "internal.h"
+
+#include "../include/narsil_core.h"
+
+#include <stdatomic.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+static int32_t capacity_word(const narsil_graph *graph, uint32_t word) {
+  int32_t capacity = load_word(graph->header, word);
+  return capacity < 0 ? 0 : capacity;
+}
+
+static narsil_status claim_upper_lists(const narsil_graph *graph, int32_t top_layer, int32_t *upper_base) {
+  *upper_base = 0;
+  if (top_layer < 1) { return NARSIL_OK; }
+  int64_t words = (int64_t)top_layer * ((int64_t)list_limit(graph, 1) + NARSIL_LIST_WORDS_OVER_NEIGHBOURS);
+  _Atomic(int32_t) *used = atomic_word(graph->header, NARSIL_GRAPH_WORD_UPPER_USED);
+  for (;;) {
+    int32_t offset = atomic_load(used);
+    if (offset < 0 || (int64_t)offset + words > capacity_word(graph, NARSIL_GRAPH_WORD_UPPER_CAPACITY)) {
+      return NARSIL_NEEDS_ROOM;
+    }
+    if (!atomic_compare_exchange_strong(used, &offset, (int32_t)(offset + words))) { continue; }
+    memset(graph->upper + offset, 0, (size_t)words * sizeof(int32_t));
+    *upper_base = offset + 1;
+    return NARSIL_OK;
+  }
+}
+
+static void raise_slots(const narsil_graph *graph, int32_t slots) {
+  _Atomic(int32_t) *word = atomic_word(graph->header, NARSIL_GRAPH_WORD_SLOTS);
+  int32_t seen = atomic_load(word);
+  while (seen < slots && !atomic_compare_exchange_strong(word, &seen, slots)) {}
+}
+
+static narsil_status create_node(const narsil_graph *graph, const narsil_place_request *request) {
+  int32_t ordinal = request->ordinal;
+  if (ordinal >= capacity_word(graph, NARSIL_GRAPH_WORD_SLOT_CAPACITY)) { return NARSIL_NEEDS_ROOM; }
+  if (atomic_load(atomic_byte(graph->node_levels, (uint32_t)ordinal)) != 0) { return NARSIL_INVALID_ARGUMENT; }
+  int32_t upper_base = 0;
+  narsil_status status = claim_upper_lists(graph, request->top_layer, &upper_base);
+  if (status != NARSIL_OK) { return status; }
+
+  _Atomic(uint8_t) *tombstone = atomic_byte(graph->tombstones, (uint32_t)ordinal);
+  if (atomic_load(tombstone) == 1) {
+    atomic_fetch_sub(atomic_word(graph->header, NARSIL_GRAPH_WORD_TOMBSTONE_COUNT), 1);
+    atomic_store(tombstone, 0);
+  }
+  size_t base_stride = (size_t)list_limit(graph, 0) + NARSIL_LIST_WORDS_OVER_NEIGHBOURS;
+  graph->upper_base[ordinal] = upper_base;
+  graph->level0[(size_t)ordinal * base_stride] = 0;
+  raise_slots(graph, ordinal + 1);
+  atomic_store(atomic_byte(graph->nearest_link_due, (uint32_t)ordinal), 1);
+  atomic_store(atomic_byte(graph->node_levels, (uint32_t)ordinal), (uint8_t)(request->top_layer + 1));
+  atomic_fetch_add(atomic_word(graph->header, NARSIL_GRAPH_WORD_NODE_COUNT), 1);
+  return NARSIL_OK;
+}
+
+static void retire_unlinked_node(const narsil_graph *graph, int32_t ordinal) {
+  uint8_t live = 0;
+  if (atomic_compare_exchange_strong(atomic_byte(graph->tombstones, (uint32_t)ordinal), &live, 1)) {
+    atomic_fetch_add(atomic_word(graph->header, NARSIL_GRAPH_WORD_TOMBSTONE_COUNT), 1);
+  }
+}
+
+static int claim_entry_if_empty(const walk_context *context, const narsil_place_request *request) {
+  int32_t *header = context->graph->header;
+  if (load_word(header, NARSIL_GRAPH_WORD_ENTRY_POINT) != NO_ENTRY_POINT) { return 0; }
+  entry_lock(context);
+  int claimed = load_word(header, NARSIL_GRAPH_WORD_ENTRY_POINT) == NO_ENTRY_POINT;
+  if (claimed) {
+    atomic_store(atomic_word(header, NARSIL_GRAPH_WORD_ENTRY_POINT), request->ordinal);
+    atomic_store(atomic_word(header, NARSIL_GRAPH_WORD_TOP_LAYER), request->top_layer);
+  }
+  entry_unlock(context);
+  return claimed;
+}
+
+static void raise_entry(const walk_context *context, const narsil_place_request *request) {
+  int32_t *header = context->graph->header;
+  entry_lock(context);
+  if (request->top_layer > load_word(header, NARSIL_GRAPH_WORD_TOP_LAYER)) {
+    atomic_store(atomic_word(header, NARSIL_GRAPH_WORD_ENTRY_POINT), request->ordinal);
+    atomic_store(atomic_word(header, NARSIL_GRAPH_WORD_TOP_LAYER), request->top_layer);
+  }
+  entry_unlock(context);
+}
+
+static int32_t *selection_of(const narsil_workspace *workspace, int32_t layer) {
+  return workspace->selections + ((size_t)layer * workspace->selection_stride);
+}
+
+static narsil_status reserve_for_placement(const walk_context *context, const narsil_place_request *request) {
+  narsil_workspace *workspace = context->workspace;
+  int32_t ef_construction = load_word(context->graph->header, NARSIL_GRAPH_WORD_EF_CONSTRUCTION);
+  if (ef_construction <= 0) { return NARSIL_INVALID_ARGUMENT; }
+  if (request->ordinal >= capacity_word(context->graph, NARSIL_GRAPH_WORD_SLOT_CAPACITY)) { return NARSIL_NEEDS_ROOM; }
+  narsil_status status = list_reserve(&workspace->layer_candidates, (uint32_t)ef_construction);
+  if (status == NARSIL_OK) { status = list_reserve(&workspace->link_candidates, MAX_NEIGHBOURS_PER_LIST); }
+  if (status == NARSIL_OK) { status = workspace_reserve_entry_points(workspace, (uint32_t)ef_construction); }
+  if (status == NARSIL_OK) { status = workspace_reserve_visited(workspace, (uint32_t)request->ordinal + 1); }
+  if (status == NARSIL_OK) { status = reserve_last_links(workspace); }
+  if (status != NARSIL_OK) { return status; }
+  return workspace_reserve_links(workspace, context->graph, (uint32_t)request->top_layer + 1);
+}
+
+static narsil_status select_every_layer(const walk_context *context, const narsil_place_request *request,
+                                        link_span span) {
+  narsil_workspace *workspace = context->workspace;
+  uint32_t ef_construction = (uint32_t)load_word(context->graph->header, NARSIL_GRAPH_WORD_EF_CONSTRUCTION);
+  scored_list *found = &workspace->layer_candidates;
+  if (ef_construction == 0 || ef_construction > found->capacity) { return NARSIL_INVALID_ARGUMENT; }
+  narsil_candidates candidates = {found->ordinals, found->distances, found->capacity, 0};
+  use_single_entry(workspace, load_word(context->graph->header, NARSIL_GRAPH_WORD_ENTRY_POINT));
+  narsil_status status = descend_layers(context, span.graph_top, request->top_layer + 1, &candidates);
+  for (int32_t layer = span.link_top; layer >= 0 && status == NARSIL_OK; layer--) {
+    layer_search search = {ef_construction, layer, 0, {NULL, 0}};
+    status = search_layer(context, search, &candidates);
+    if (status != NARSIL_OK) { break; }
+    if (candidates.count > 0) {
+      memcpy(workspace->entry_points, candidates.ordinals, (size_t)candidates.count * sizeof(int32_t));
+      workspace->entry_point_count = candidates.count;
+    }
+    found->count = candidates.count;
+    workspace->selection_counts[layer] =
+        select_neighbours(context, found, list_limit(context->graph, layer), selection_of(workspace, layer));
+  }
+  return status;
+}
+
+static void write_own_lists(const walk_context *context, const narsil_place_request *request, int32_t link_top) {
+  const narsil_workspace *workspace = context->workspace;
+  node_lock(context, request->ordinal);
+  for (int32_t layer = link_top; layer >= 0; layer--) {
+    node_layer position = {request->ordinal, layer};
+    list_write_counted(context, position, selection_of(workspace, layer), workspace->selection_counts[layer]);
+  }
+  node_unlock(context, request->ordinal);
+}
+
+static void link_neighbours_back(const walk_context *context, const narsil_place_request *request, int32_t link_top) {
+  const narsil_workspace *workspace = context->workspace;
+  for (int32_t layer = link_top; layer >= 0; layer--) {
+    const int32_t *selected = selection_of(workspace, layer);
+    for (uint32_t i = 0; i < workspace->selection_counts[layer]; i++) {
+      node_layer position = {selected[i], layer};
+      if (layer > node_top_layer(context, selected[i])) { continue; }
+      node_lock(context, selected[i]);
+      list_add(context, position, request->ordinal);
+      list_prune(context, position);
+      node_unlock(context, selected[i]);
+    }
+  }
+}
+
+static narsil_status link_node(walk_context *context, const narsil_place_request *request) {
+  link_span span = {load_word(context->graph->header, NARSIL_GRAPH_WORD_TOP_LAYER), 0};
+  int32_t former_entry = load_word(context->graph->header, NARSIL_GRAPH_WORD_ENTRY_POINT);
+  span.link_top = request->top_layer < span.graph_top ? request->top_layer : span.graph_top;
+  if (span.link_top >= 0) {
+    narsil_status status = select_every_layer(context, request, span);
+    if (status != NARSIL_OK) { return status; }
+    write_own_lists(context, request, span.link_top);
+    link_neighbours_back(context, request, span.link_top);
+  }
+  if (request->top_layer <= span.graph_top) { return NARSIL_OK; }
+  raise_entry(context, request);
+  int demoted = former_entry != NO_NODE &&
+                load_word(context->graph->header, NARSIL_GRAPH_WORD_ENTRY_POINT) != former_entry &&
+                is_live(context, former_entry);
+  if (demoted && incoming_count(context, former_entry) == 0) { note_node_left_unlinked(context); }
+  return NARSIL_OK;
+}
+
+static narsil_status place_under_the_graph_lock(walk_context *context, const narsil_place_request *request) {
+  narsil_status status = reserve_for_placement(context, request);
+  if (status == NARSIL_OK) { status = create_node(context->graph, request); }
+  if (status != NARSIL_OK) { return status; }
+  status = read_graph_extent(context);
+  if (status == NARSIL_OK && !claim_entry_if_empty(context, request)) { status = link_node(context, request); }
+  if (status != NARSIL_OK) { retire_unlinked_node(context->graph, request->ordinal); }
+  return status;
+}
+
+narsil_status narsil_place(narsil_workspace *workspace, const narsil_graph *graph, const narsil_store *store,
+                           const narsil_place_request *request) {
+  if (request == NULL || request->ordinal < 0) { return NARSIL_INVALID_ARGUMENT; }
+  if (request->top_layer < 0 || request->top_layer >= NARSIL_MAX_PLACEMENT_LAYERS) { return NARSIL_INVALID_ARGUMENT; }
+  walk_context context;
+  narsil_status status = begin_walk(&context, workspace, graph, store, request->metric);
+  if (status != NARSIL_OK) { return status; }
+  if (request->thread_slot >= graph->thread_slots) { return NARSIL_INVALID_ARGUMENT; }
+  const float *vector = stored_vector(store, request->ordinal, workspace->placed_vector);
+  if (vector == NULL) { return NARSIL_INVALID_ARGUMENT; }
+  context.thread_slot = request->thread_slot;
+  if (store->file_count == 0) {
+    walk_with_query(&context, vector);
+  } else {
+    walk_with_placement_query(&context, vector);
+  }
+  if (!context.uses_codes) { context.query.magnitude = store->magnitudes[request->ordinal]; }
+
+  if (request->graph_held_alone) {
+    if (load_word(graph->header, NARSIL_GRAPH_WORD_LOCK) != NARSIL_GRAPH_HELD_ALONE) {
+      return NARSIL_GRAPH_NOT_HELD_ALONE;
+    }
+    return place_under_the_graph_lock(&context, request);
+  }
+  graph_lock_shared(graph, request->thread_slot);
+  status = place_under_the_graph_lock(&context, request);
+  graph_unlock_shared(graph, request->thread_slot);
+  return status;
+}