3.3 Monitoring the database

The predicate rdf_monitor/2 allows registrations of call-backs with the RDF store. These call-backs are typically used to keep other databases in sync with the RDF store. For example, library(library(semweb/rdf_persistency)) monitors the RDF store for maintaining a persistent copy in a set of files and library(library(semweb/rdf_litindex)) uses added and deleted literal values to maintain a fulltext index of literals.

rdf_monitor(:Goal, +Mask)

Goal is called for modifications of the database. It is called with a single argument that describes the modification. Defined events are:

assert(+S, +P, +O, +DB)

A triple has been asserted.

retract(+S, +P, +O, +DB)

A triple has been deleted.

update(+S, +P, +O, +DB, +Action)

A triple has been updated.

new_literal(+Literal)

A new literal has been created. Literal is the argument of literal(Arg) of the triple's object. This event is introduced in version 2.5.0 of this library.

old_literal(+Literal)

The literal Literal is no longer used by any triple.

transaction(+BeginOrEnd, +Id)

Mark begin or end of the commit of a transaction started by rdf_transaction/2. BeginOrEnd is begin(Nesting) or end(Nesting). Nesting expresses the nesting level of transactions, starting at `0' for a toplevel transaction. Id is the second argument of rdf_transaction/2. The following transaction Ids are pre-defined by the library:

parse(Id)

A file is loaded using rdf_load/2. Id is one of file(Path) or stream(Stream).

unload(DB)

All triples with source DB are being unloaded using rdf_unload/1.

reset

Issued by rdf_reset_db/0.

load(+BeginOrEnd, +Spec)

Mark begin or end of rdf_load_db/1 or load through rdf_load/2 from a cached file. Spec is currently defined as file(Path).

rehash(+BeginOrEnd)

Marks begin/end of a re-hash due to required re-indexing or garbage collection.

Mask is a list of events this monitor is interested in. Default (empty list) is to report all events. Otherwise each element is of the form +Event or -Event to include or exclude monitoring for certain events. The event-names are the functor names of the events described above. The special name all refers to all events and assert(load) to assert events originating from rdf_load_db/1. As loading triples using rdf_load_db/1 is very fast, monitoring this at the triple level may seriously harm performance.

This predicate is intended to maintain derived data, such as a journal, information for undo, additional indexing in literals, etc. There is no way to remove registered monitors. If this is required one should register a monitor that maintains a dynamic list of subscribers like the XPCE broadcast library. A second subscription of the same hook predicate only re-assignes the mask.

The monitor hooks are called in the order of registration and in the same thread that issued the database manipulation. To process all changes in one thread they should be send to a thread message queue. For all updating events, the monitor is called while the calling thread has a write lock on the RDF store. This implies that these events are processed strickly synchronous, even if modifications originate from multiple threads. In particular, the transaction begin, ... updates ... end sequence is never interleaved with other events. Same for load and parse.