OSAF chose a non-locking transaction model for Chandler’s repository. One advantage of that choice is that items are never locked. Conflicts between concurrent changes to the same item in different repository views are detected and reported at the time they’re committed to persistent storage - sophisticated version merging is planned but not yet implemented.

One disadvantage of that choice is that as items get changed in several views, when a view is refreshed - right after a commit operation - out-of-date items held by this view are marked stale and are no longer usable. The programmer must fetch the item again from the repository via a find() call to get a fresh item instance.

One consequence is that keeping python pointers to items past commit operations is unsafe and unpredictable. A workaround has been to keep pointers to their UUID instead and always find the items by these cached UUIDs when an item’s instance is needed again. While functional, this workaround is somewhat cumbersome.

Given that only the Chandler attributes of an item instance are persisted and that the innards of Chandler attributes are entirely controlled by the data model implementation, except for collection values, it is actually possible to refresh an item in-place after it was marked stale during a repository view refresh, thereby avoiding that the item’s python pointer is not marked stale.

But guaranteeing that item pointers never go stale contradicts repository view pruning. A repository view is pruned of its least used items when it exceeds by 10% a certain item count (currently 10,000, an arbitrary value) so that its item count goes below 90% of that threshhold.

Therefore, a new API was added for pinning an item into memory. Pinning an item guarantees that the item’s python pointer is never marked stale, unless the item is actually deleted. Overusing pinned items defeats repository view pruning and should be used sparingly. Because schema items are so essential to Chandler’s operation they are pinned into memory by default. Programmers needs to decide when to pin and unpin non schema items into memory on an as-needed basis.

To pin an item into memory : item.setPinned()
To unpin an item from memory: item.setPinned(False)