documented methods for detecting replicant reliability, created stub methods

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Storage / DBI / Replicated / Replicant.pm

diff --git a/lib/DBIx/Class/Storage/DBI/Replicated/Replicant.pm b/lib/DBIx/Class/Storage/DBI/Replicated/Replicant.pm
index 8d53297..59ac66e 100644 (file)
--- a/lib/DBIx/Class/Storage/DBI/Replicated/Replicant.pm
+++ b/lib/DBIx/Class/Storage/DBI/Replicated/Replicant.pm
@@ -32,6 +32,13 @@ This is a boolean which allows you to programmatically activate or deactivate a
 replicant from the pool.  This way to you do stuff like disallow a replicant
 when it get's too far behind the master, if it stops replicating, etc.
 
+This attribute DOES NOT reflect a replicant's internal status, i.e. if it is
+properly replicating from a master and has not fallen too many seconds behind a
+reliability threshold.  For that, use L</is_replicating>  and L</lag_behind_master>.
+Since the implementation of those functions database specific (and not all DBIC
+supported DB's support replication) you should refer your database specific
+storage driver for more information.
+
 =cut
 
 has 'active' => (
@@ -42,7 +49,6 @@ has 'active' => (
     default=>1,
 );
 
-
 =head1 METHODS
 
 This class defines the following methods.
@@ -59,6 +65,29 @@ around '_query_start' => sub {
        $self->$method("DSN: $dsn SQL: $sql", @bind);
 };
 
+=head2 is_replicating
+
+A boolean that reports if a particular L<DBIx::Class::Storage::DBI> is set to
+replicate from a master database.  Default is false, which is the result
+returned by databases that don't support replication.
+
+=cut
+
+sub is_replicating {
+       my $self = shift @_;
+}
+
+=head2 lag_behind_master
+
+Returns a number that represents a certain amount of lag behind a master db
+when a given storage is replicating.  The number is database dependent, but
+starts at zero, which is the default, and increases with the amount of lag.
+
+=cut
+
+sub lag_behind_master {
+    my $self = shift @_;
+}
 
 =head1 AUTHOR