## resource_states.txt Version 0.03

# Author: Frank Liepold frank.liepold@1und1.de

# Can be printed with a2ps -R --rows=1 --columns=1 -l 130 -L101 resource_states.txt
#
# Describes the states of mars resources

===================================== RESOURCE =====================================================================

The state of a resource comprises the states of 3 objects (role, disk, replication) taking the following values.

The actuality of the state values of secondary resources are determined by the timestamp of the last update of
the symlink <actuality-symlink> (at the momemt = /mars/alive-<host>), which is exclusively written by the primary.

role: the states are pairwise disjoint
----
   primary  : server
   secondary: client
   none     : no resource joined

disk:                   the states are *not* pairwise disjoint. The exclusive values are indicated by "[ex]".
----
   detached           [ex]  : underlying device may be used by other applications

   outdated-fetch           :     role = secondary
                              AND consistent
                              AND not all logfiles have been fetched from the primary

   outdated-apply                role = secondary
                              AND consistent
                              AND NOT all fetched logfiles have been applied
   uptodate          [ex]   :     consistent
                              AND [ role = primary OR [     role = secondary
                                                        AND all logfiles have been fetched from the primary
                                                        AND all logfiles are applied
                                                      ]
                                  ]
   inconsistent     [ex]    : none of the four states above (a sync, restore or similar action is necessary
                              to reach a consistent state)

repl: the state values are *not* pairwise disjoint. The exclusive values are indicated by "[ex]"
----
        abbreviation: consistent_disk = [ disk NOT [ detached | inconsistent ] ] 
                
   replicating            [ex]  : role = primary AND consistent_disk AND can write logfiles 
   primary_unreachable          : role = secondary AND primary does not update the symlink <actuality-symlink>
   syncing                [ex]  :     role = secondary
                                  AND disk = inconsistent
                                  AND synching from primary
                                  AND NOT primary_unreachable
   paused_sync            [ex]  :     role = secondary
                                  AND disk = inconsistent
                                  AND  manually prevented from syncing
                                  AND NOT primary_unreachable
   paused_fetch                 :     role = secondary
                                  AND consistent_disk
                                  AND manually prevented from fetching logfiles
                                  AND NOT primary_unreachable
   paused_apply                 :     role = secondary
                                  AND consistent_disk
                                  AND manually prevented from applying logfiles
   replaying              [ex]  :     role = secondary
                                  AND consistent_disk
                                  AND NOT synching AND NOT paused_synching
                                  AND NOT paused_fetch
                                  AND NOT paused_apply
                                  AND NOT primary_unreachable

As an example  the state "resource = secondary, logfiles are to be fetched but fetching
has been manually stopped, and applying some logfiles is on it's way" would be represented by:

role = secondary
disk = outdated-fetch & outdate-apply
repl = replaying | paused_fetch

The amount of data to fetch resp. to apply should be displayed, too.


For data consistence the states of the following objects are important too:

device (the "underlying" device):
------
   locked  : cannot be opened by other applications
   unlocked: usable as a normal block device by other applications
   unused  : not used by any application

mars_device:
-----------
    usable   : can be used in "normal" ways
    invisible: what the name means
    undef    : not existent

===========
    Hint: Of course the states are not independent, e.g.:

    disk != detached => device = locked
    repl = synching && role = secondary => disk inconsistent

    These action independent rules will not be regarded here and must be guaranteed by tests.