Skip to main content

Performance

This page describes where the engine spends work. The measured cost of each call is in The price of a call.

The identity path and the key path​

Setup shared by the examples on this page
import { OIMDB, OIMEffectService, createOIMEntityContentService, createOIMSlotCollectionService } from '@oimdb/core';

type Card = { id: string; title: string; deck: string };

const db = new OIMDB();
const effectService = OIMEffectService.INSTANCE;
const cardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService<Card>() });
const entityService = cardService.slotContentService;
const cards = cardService.createStoreSlot(db);
const slot = cardService.getSlotByKey(cards, 'c1');
const patch: Partial<Card> = { title: 'ACE' };
const handler = (): void => {};
entityService.updateEntity(slot, patch); // you already hold the identity
const found = cardService.peekSlotByKey(cards, 'c1'); // one Map read
if (found !== undefined) entityService.updateEntity(found, patch);

Every write but the whole-value writeSlotContentByKey takes the slot, so the map read is always a call you can see: peekSlotByKey or getSlotByKey. If a key arrives from outside (a route param, a server payload), the read is unavoidable. If you already hold the slot, from the return value of writeSlotContentByKey or from an earlier getSlotByKey, going back through the key is pure waste.

Not measured: a price pair for each against its own floor (peekSlotByKey plus updateEntity against a map.get plus a store, updateEntity against a bare field assignment) on this engine.

A column of a slot is its own identity​

A write reports the columns it moved, and each column anybody has subscribed to is a slot with its own dependent list:

const deckColumn = slot.getColumnSlot('deck');
effectService.createEffect(db, handler, [deckColumn]);
entityService.updateEntity(slot, { title: 'ACE' }); // never reaches handler
entityService.updateEntity(slot, { deck: 'hearts' }); // reaches handler

It is lazy on both sides. A column identity is minted only by the door that asks for it (the collection's holdColumnSlot, or its getColumnSlot inside a subscription), and it is dropped once its last effect is disposed and nothing holds it. A write never mints one: the service's column owner skips a moved column that has no slot filed.

So an entity type nobody watches by column pays one field read (slot.columnSlotStore === undefined) per write and nothing else. A slot watched on one column out of twenty pays one map probe per moved column against a map holding one entry.

Not measured: the per-write cost of that field read, and the cost of the probe against a populated column map.

Delivery is coalesced, and the coalescing is a stamp​

Whatever a frame's writes touched, each identity's effects run once. The mechanism is the clock stamp on the slot compared against the clock reading the last frame closed at (OIMChannelService.isChangedInCurrentFrame). It is an integer comparison, not a lookup in a set.

Not measured: the price of a write that lands on an already-stamped slot against one that lands on a clean one.

Derivations are asked, not woken​

Nothing schedules a computed slot, nothing marks it, and no frame walks to it. It settles when a reader asks, and the settle asks one question first: has anything I read moved?

The chain short-circuits on that question. A recursive settle returns without deriving when nothing under it moved, so a chain over quiet roots is a walk of integer comparisons, and a chain whose roots moved derives only the levels whose inputs actually changed. filter → sort → page costs one comparison when an entity moves without leaving the filter, instead of sorting everything again.

Not measured: the cost of a quiet settle per chain level, and the crossover against recomputing.

Ordering is a derivation over an index​

A bucket on the set-driven or array-driven content service never sorts: its order is the caller's. The sorted-array-driven one (createOIMSlotCollectionSortedArrayIndexService) keeps the order at the write instead. The other sorted list is createOIMSortedComputedService({ indexService, sortColumns?, comparator? }), whose createSortedStoreSlot(indexStoreSlot) builds it over one index store slot: a pull computed re-derived on the read that asks. Its sources are the bucket slot (membership) and one bucket column slot per sort column, so a write that changes no sort column on a member does not re-derive it; with only a comparator the sources are the bucket slot and the bucket's any-column slot (member content, and a join or leave too), and any member write re-sorts. A re-sort that yields the same sequence keeps the previous array.

Not measured: the cost of a re-sort against keeping the order at the write, at several bucket sizes.

Emptying a bucket​

writeSlotContent and clearSlotContent empty a bucket in one call, with zero element moves. Removing slots one at a time from an array-driven bucket closes the gap with a splice each time, so evicting n slots that way costs n(n-1)/2 element moves: 499 500 for a thousand.

Fast properties​

A field read is a fixed-offset load only while the object is on fast properties and every object reaching the read shares one hidden class. An object in dictionary mode pays a hash lookup per read, and a site that sees too many hidden classes stops caching altogether. V8 reports both states directly, so they are checked as facts, not timed:

  • every slot kind — entity, bucket, computed, column — is one object literal with every field present at birth; nothing adds a field later and nothing deletes one;
  • per-index state on an entity slot lives in the indexKeys array, so indexes add no properties;
  • every slot of a kind keeps one hidden class through holds, effects, moves between buckets, patches and release deadlines;
  • neither writer deletes a column: a column that leaves is written undefined, in place or into a spread copy, so an entity keeps its hidden class when a column leaves, checked on a forty-column entity under both writers;
  • three slot shapes reach the write door, one below V8's polymorphic ceiling of four, and four reach holdSlot.

These are facts about object layout read from V8 itself, not timings. The one case outside the engine: an entity handed in with a few hundred fields is in dictionary mode before it arrives.

See Object shapes for how each part of the engine is laid out to keep this.

Choosing strategies​

Both strategies of each fork are shipped, and neither strategy of any fork has a measured price on this engine. The guidance below rests on architecture, not measurements.

ForkPick the first strategy whenPick the second when
createOIMInPlaceEntityWriter / createOIMReplacingEntityWriterconsumers are subscription-drivensomething downstream compares by reference
OIMSetBucketContentService / OIMPositionalArrayBucketContentServiceyou never render this bucket in the caller's orderyou do, and you want the reorder commands
OIMPositionalArrayBucketContentService / OIMBucketUniqueMemberSlotsArrayServiceduplicates in a bucket are meaningfula slot must appear once
createOIMSortedComputedService with sortColumns / with only a comparatorthe order is a function of named columnsthe comparator reads what no column list can name, so any member write re-sorts
createOIMSortedComputedService / createOIMSlotCollectionSortedArrayIndexServicethe list is read less often than it is writtenthe list is read on every frame, so the order is kept at the write
createOIMSlotCollectionService / createOIMSlotCollectionIndexServicewhat a bucket holds is a fact about a responsebelonging really is a function of the entity

Pick one strategy per fork for the whole app unless a task needs two: the engine's shared call sites see every strategy in the process, and five of one kind make a site megamorphic. See Mixing strategies in one app.

Where to next​