# Io Reference

Databases / Obsidian / PDB

An arbitrary graph database with support for on-disk garbage collection. Example use:

#### Setup

    PDB open
    PDB root atPut("users", PMap clone)
    PDB sync
    PDB close

PMap is a Map/Dictionary whose keys are lazily loaded from the database. PDB root is the root PMap in the database and the root object used for PDB's garbage collector. PDB sync needs to be called to write any changes to the database.

#### Defining a Persistent Object

    User := Object clone pSlots(name, email)

The pSlots(), declares which slots on the object should be persisted. The List, Date, Sequence and Number primitives already know how to persist themselves.

#### Inserting a Persistent Object

    PDB open
    user := User clone setName("steve") setEmail("steve@foo.com")
    PDB root users atPut("steve", user)
    PDB sync
    PDB close

#### Accessing a Persistent Object

    user := PDB root users at("steve")
    writeln("user name = ", user name, " email = ", user email)

#### Updating a Persistent Object

    user setEmail("steve@newDomain.com")
    PDB sync

PDB sync will scan all persistent objects in the vm and save any with changes to their persistent slots. If the object was already in the database, only its updated slots will be written.

#### Removing an entry in a PMap

    PDB root users removeAt("steve")

#### Removing a persistent object

This is never done explicitly, instead calling:

    PDB collectGarbage

Will remove all objects unreachable by the reference graph from the root PMap.

Notes: Currently, PDB is a singleton.

addObjectToPersist

Register an object to be persisted in the next PDB sync.
close

Close the persistence database.
collectGarbage

Remove from PDB all objects not accessible via the root object.
newId

Generate a new PDB id number for use as a persistent object's ppid.
objectAtPpid

Return the object associated in the database with a ppid.
reopen

Sync, close and reopen the PDB store.
root

Return the root PMap object used to store and retrieve persistent objects and their slots.
show

Print to standard output a listing of all objects and IDs stored in PDB.
sync

Immediately persist data for all objects marked dirty by Collector whose shouldPersistByDefault is true, or that have specifically requested to be persisted since the last sync via addObjectToPersist.