NAME

Prophet::Replica

DESCRIPTION

A base class for all Prophet replicas.

METHODS

get_handle

Determines what replica class to use and instantiates it. Returns the new replica object.

store_local_metadata KEY => VALUE

Takes a key and a value.

Store some bit of metadata in a durable local datastore. Metadata isn't propagated when replicas are synced.

Returns true or false.

fetch_local_metadata KEY

Takes a scalar key.

Fetches a bit of metadata from the local metadata store.

Returns the value of the key found in the local metadata store.

Returns undef if there's no value for the key in the local metadata store.

_url_to_replica_class

Returns the replica class for the given url based on its scheme.

import_changesets { from => Prophet::Replica ... }

Given a Prophet::Replica to import changes from, traverse all the changesets we haven't seen before and integrate them into this replica.

This routine calls traverse_changesets on the 'from' replica, passing in the most recent changeset the current replica has seen and a callback routine which calls integrate_changeset on the local replica.

That callback itself takes a callback, after_integrate_changeset , which a replica implementation can use to perform some action after a changeset is integrated into a peer. after_integrate_changeset takes a paramhash, currently with only a single key, 'changeset'.

import_resolutions_from_remote_replica { from => Prophet::Replica ... }

Takes a Prophet::Replica object (and possibly some optional arguments) and imports its resolution changesets into this replica's resolution database.

Returns immediately if either the source replica or the target replica lack a resolution database.

integrate_changeset Prophet::ChangeSet

Given a Prophet::ChangeSet, integrate each and every change within that changeset into the handle's replica.

If there are conflicts, generate a nullification change, figure out a conflict resolution and apply the nullification, original change and resolution all at once (as three separate changes).

If there are no conflicts, just apply the change.

This routine also records that we've seen this changeset (and hence everything before it) from both the peer who sent it to us AND the replica which originally created it.

record_changeset_and_integration Prophet::ChangeSet

Given a Prophet::ChangeSet, integrate each and every change within that changeset into the handle's replica.

If the state handle is in the middle of an edit, the integration of this changeset is recorded as part of that edit; if not, it is recorded as a new edit.

last_changeset_from_source $SOURCE_UUID

Returns the last changeset id seen from the replica identified by $SOURCE_UUID.

has_seen_changeset { source_uuid => <uuid>, sequence_no => <int> }

Returns true if we've previously integrated this changeset, even if we originally received it from a different peer.

changeset_will_conflict Prophet::ChangeSet

Returns true if any change that's part of this changeset won't apply cleanly to the head of the current replica.

conflicts_from_changeset Prophet::ChangeSet

Returns a "" in Prophet::Conflict object if the supplied "" in Prophet::ChangeSet will generate conflicts if applied to the current replica.

Returns undef if the current changeset wouldn't generate a conflict.

should_accept_changeset { from => Prophet::Replica, changeset => Prophet::ChangeSet }

Returns true if this replica hasn't yet seen the changeset changeset.

fetch_changesets { after => SEQUENCE_NO }

Fetch all changesets from this replica after the local sequence number SEQUENCE_NO.

Returns a reference to an array of "" in Prophet::ChangeSet objects.

See also traverse_changesets for replica implementations to provide streamly interface.

methods to be implemented by a replica backend

uuid

Returns this replica's uuid.

latest_sequence_no

Returns the sequence # of the most recently committed changeset.

find_or_create_luid { uuid => UUID }

Finds or creates a LUID for the given UUID.

find_uuid_by_luid { luid => LUID }

Finds the UUID for the given LUID. Returns undef if the LUID is not known.

_create_luid ( 'uuid' => 'luid' )

Given a UUID => LUID hash mapping, return a new unused LUID (one higher than the mapping's current highest luid).

_do_userdata_read $PATH $DEFAULT

Returns a reference to the parsed JSON contents of the file given by $PATH in the replica's userdata directory.

Returns $DEFAULT if the file does not exist.

_do_userdata_write $PATH $VALUE

serializes $VALUE to JSON and writes it to the file given by $PATH in the replica's userdata directory, creating parent directories as necessary.

_upstream_replica_cache_file

A string representing the name of the file where replica URLs that have been previously pulled from are cached.

_read_cached_upstream_replicas

Returns a list of cached upstream replica URLs, or an empty list if there are no cached URLs.

_write_cached_upstream_replicas @REPLICAS

writes the replica URLs given by @REPLICAS to the upstream replica cache file.

_guid2luid_file

The file in the replica's userdata directory which contains a serialized JSON UUID => LUID hash mapping.

_read_guid2luid_mappings

Returns a UUID => LUID hashref for this replica.

_write_guid2luid_mappings ( 'uuid' => 'luid' )

Writes the given UUID => LUID hash map to /_guid2luid_file as serialized JSON.

_read_luid2guid_mappings

Returns a LUID => UUID hashref for this replica.

traverse_changesets { after => SEQUENCE_NO, until => SEQUENCE_NO, callback => sub { my %data = (changeset => undef, @_} }

Walk through each changeset in the replica after SEQUENCE_NO, calling the callback for each one in turn.

can_read_changesets

Returns true if this source is one we know how to read from (and have permission to do so).

can_write_changesets

Returns true if this source is one we know how to write to (and have permission to write to).

Returns false otherwise.

record_resolutions Prophet::ChangeSet

Given a resolution changeset, record all the resolution changesets as well as resolution records in the local resolution database.

Called ONLY on local resolution creation. (Synced resolutions are just synced as records.)

_record_resolution Prophet::Change

Called ONLY on local resolution creation. (Synced resolutions are just synced as records.)

routines dealing with integrating changesets into a replica

record_changes Prophet::ChangeSet

Inside an edit (transaction), integrate all changes in this changeset and then call the _after_record_changes() hook.

integrate_changes Prophet::ChangeSet

This routine is called by "record_changes" with a Prophet::ChangeSet object. It integrates all changes from that object into the current replica.

All bookkeeping, such as opening and closing an edit, is done by "record_changes".

If your replica type needs to play games to integrate multiple changes as a single record, this is what you'd override.

integrate_change Prophet::Change <Prophet::ChangeSet>

Integrates the given change into the current replica. Used in "integrate_changes".

record_integration_of_changeset Prophet::ChangeSet

This routine records the immediately upstream and original source uuid and sequence numbers for this changeset. Prophet uses this data to make sane choices about later replay and merge operations

routines which need to be implemented by any Prophet backend store

uuid

Returns this replica's UUID.

create_record { type => $TYPE, uuid => $UUID, props => { key-value pairs } }

Create a new record of type $TYPE with uuid $UUID within the current replica.

Sets the record's properties to the key-value hash passed in as the props argument.

If called from within an edit, it uses the current edit. Otherwise it manufactures and finalizes one of its own.

delete_record {uuid => $UUID, type => $TYPE }

Deletes the record $UUID of type $TYPE from the current replica.

Manufactures its own new edit if $self-current_edit> is undefined.

set_record_props { uuid => $UUID, type => $TYPE, props => {hash of kv pairs }}

Updates the record of type $TYPE with uuid $UUID to set each property defined by the props hash. It does NOT alter any property not defined by the props hash.

Manufactures its own current edit if none exists.

get_record_props { uuid => $UUID, type => $TYPE, root => $ROOT }

Returns a hashref of all properties for the record of type $TYPE with uuid $UUID.

'root' is an optional argument which you can use to pass in an alternate historical version of the replica to inspect. Code to look at the immediately previous version of a record might look like:

    $handle->get_record_props(
        type => $record->type,
        uuid => $record->uuid,
        root => $self->repo_handle->fs->revision_root( $self->repo_handle->fs->youngest_rev - 1 )
    );

record_exists {uuid => $UUID, type => $TYPE }

Returns true if the record in question exists and false otherwise.

list_records { type => $TYPE }

Returns a reference to a list of all the records of type $TYPE.

list_records

Returns a reference to a list of all the known types in your Prophet database.

type_exists { type => $type }

Returns true if we have any records of type $TYPE.

routines which need to be implemented by any _writable_ prophet backend store

optional routines which are provided for you to override with backend-store specific behaviour

_after_record_changes Prophet::ChangeSet

Called after the replica has integrated a new changeset but before closing the current transaction/edit.

The SVN backend, for example, used this to record author metadata about this changeset.

_set_original_source_metadata_for_current_edit

Sets original_source_uuid and original_sequence_no for the current edit.

helper routines

log $MSG

Logs the given message to STDERR (but only if the PROPHET_DEBUG environmental variable is set).

log_fatal $MSG

Logs the given message and dies with a stack trace.

changeset_creator

The string to use as the creator of a changeset.

display_name_for_replica [uuid]

If the user has a "friendly" name for this replica, then use it. Otherwise, display the replica's uuid.

If you pass in a uuid, it will be used instead of the replica's uuid.

cpanm Prophet

perl -MCPAN -e shell
install Prophet