@c Copyright (c) 2002 Kungliga Tekniska Högskolan
@c (Royal Institute of Technology, Stockholm, Sweden).
@c All rights reserved.

@c $arla: prog-disco.texi,v 1.1 2002/05/27 13:08:31 lha Exp $

@cindex Disconected operation

@chapter Disco with arla

Disconnected operation of arla.

@section The Log

The binary log is written to a file. All entries are of variable size.
A entry is never removed from the log @pxref{Log entry optimization}.

@subsection One log entry

One log entry consists of a log header with magic cookie, opcode,
checksum, and length. The entry is is always 4 byte aligned in the
logfile.  The checksum is a simple one, its just to verify that for
data corruption hasn't occured and to make sure the entry is a valid
one.

@subsection Disconnected vs connected nodes

A FCacheNode is either a @dfn{disconnected node} or a @dfn{connected
node}. The later means that the node was created when arla was in
connected mode and thus (potentially) exist on the file server.

A disconnected node on the other hand was created when is disconnected
operation. A disconnected node always have one or more entries in the
log.

@subsection Log entry offset

The offset of the entry, a unsigned 32 bit number, is called
@dfn{disco_id}. Its stored in the FCacheNode so it can be updated when
there is a operation on this node. All nodes for a FCacheEntry are
single linked list (from the newest log entry to the oldest), the
optimizer uses this to modify all previous entries from a FCacheNode.

A FCacheNode with disco_id equal to 0 is a connected node that there
have been no disconnected operation made on.

The first entry in the log is a nop entry to make sure not a
log-offset that is for a ``real'' entry.

The limit of number of entries in the log are 2^32 / the size of the
largest entry since the offset is a 32 bit number.

@c @subsection Dump log / Backup of log
@c 
@c It should be possible to extract a dump of the current state of
@c disconnected operation (all adding operations that is). This is to
@c make a backup of all changes before reitegration.

@section Log entry optimization
@anchor{Log entry optimization}

To try to preserve bandwith when reinterating there are dependencies
between entries. First we try to avoid storing data to the fileserver
that was never meant to got there. For example a file that was created
and then removed in disconnected mode, ie @code{DISCO_HEADER_NOP} is
set in the flags field in the header.

@subsection Removal operations

When a node is removed and the node is a disconnected node, the all
previous entries are optizmied away by setting a flags in their entry
headers. This make this entry/nodes be ignored by the reintergration
code and never commited to the fileserver.

@subsection Moveing a disconnected node

If a disconnected node is moved, it will be created in the target
directory instead of first being created and then moved.

@subsection Storestatus and storedata

Also, all entries for one node storestate/storestatus are compressed
to one createnode (and if needed storedata).

@section data storage

@subsection common data types

  fid - VenusFid equivalent
  storestatus - AFSStoreStatus equivalent

@enumerate

@item
@code{nop}

  needs to be smaller or equal in size then the rest

  data storage:
    header
    flags
    fid

@item
@code{storedata}

  (truncation is a storedata)

  data storage:
    header
    fid
    storestatus
    size

@item
@code{storestatus}

  data storage:
    header
    fid
    storestatus

@item
@code{createfile}

  data storage:
    header
    parentfid
    fid
    storestatus
    name[AFSNAMEMAX]

@item
@code{createsymlink}

  data storage:
    header
    parentfid
    fid
    storestatus
    name[AFSNAMEMAX]
    targetname[AFSNAMEMAX]

@item
@code{createlink}

  data storage:
    header
    parentfid
    fid
    storestatus
    name[AFSNAMEMAX]
    targetfid

@item
@code{unlink}

  data storage:
    header
    parentfid
    fid /* dup info */
    name[AFSNAMEMAX]

@item
@code{createdir}

  data storage:
    header
    parentfid
    fid /* dup info */
    storestatus
    name[AFSNAMEMAX]

@item
@code{removedir}

  data storage:
    header
    parentfid
    fid /* dup info */
    name[AFSNAMEMAX]

@end enumerate

@section reintegration

@subsection Cook-book

@enumerate

@item

make sure first entry in the log is a nop entry

@item

if nop entry or @code{DISCO_HEADER_NOP} is set, continue to next

@item

the parent fid is transformed to a connected fid (if needed)
  it this failes, we are unhappy and save this node for collision
  recovery

@item

the fid is transformed to a connected fid (if needed)
  it this failes, we are unhappy and save this node for collision
  recovery

@item

operation is performed

@item

if there is change on a fid 

@enumerate

@item

update kernelhandle

@item

update fcachehandle

@item

update directory fid for this name (if needed)

@item 

transformed fids are stored in the transformation table

@end enumerate

@end enumerate