/* $Id: pfs_nn_inodecache.x 235 2010-06-20 22:23:05Z gerd $  -*- c -*- */

/** {1:inodecache [Inodecache]} */

/** Quickly determine inode modifications.
 */

/** The inodecache is a helper service running on the namenodes.
    Only the inodecache of the coordinator must be used.
    One can get a list of available inodecache ports from the
    function [find_inodecaches] in {!Pfs_nn_coord}.

    The inodecache can quickly determine whether an [inodeinfo]
    is still up to date, or whether the sequence number of the
    [inodeinfo] is still up to date. This is faster than a regular
    [get_inodeinfo] in {!Pfs_nn_fsys} because this can happen
    outside a transaction, and because often no database query is
    required.

    The inodecache keeps the information about an inode only for
    a short time. During that period, it arranges with the coordinator
    that the cache is actively notified when the inode is modified
    (or more exactly, when a modification is committed). Note that
    there is still a small delay between this notification and the
    real check, so whatever the inodecache reports, this may already
    be outdated. Nevertheless, this information is meaningful when
    used in the right way:

    Assume you want to read the blocks of a file. You have an old
    [inodeinfo] struct at hand, and an old blocklist. So how to read
    blocks while ensuring they are recent? The way to do this is to {i
    first} trust your old information and to read the block, and {i
    then} to call the inodecache to check whether your information was
    correct. If not, you have to update your information with the more
    expensive [get_inodeinfo] and [get_blocks] calls, and to start
    over. However, if the inodecache says the information was correct,
    you know you did the right thing.  The point here is that the
    inodecache can only validate actions that already happened, but it
    cannot give guarantees for the future.
*/

#include "pfs_types.x"
#ifndef PFS_NN_INODECACHE
#define PFS_NN_INODECACHE

program Inode_cache {
    version V1 {
	/** {2 [null] } */

	void null(void) = 0;

	/** {2 [is_up_to_date] } */

	bool is_up_to_date(hyper, inodeinfo) = 1;
	/** [is_up_to_date(inode,ii)]: Checks whether [ii] is the current
	   version of the inode metadata for [inode]. Returns [true]
	   if this was the case at the moment the RPC was sent by
	   the caller.

	   Returns [false] if the inode is not known, if an error
	   occurs, or if it cannot be quickly determined that the inode
	   is actually up to date. So [false] does not necessarily imply
	   that [ii] is out of date. In this case, the client should
	   use alternate means of checking this.
	*/

	/** {2:is_up_to_date_seqno [is_up_to_date_seqno] } */

	bool is_up_to_date_seqno(hyper, hyper) = 2;
	/** [is_up_to_date(inode,seqno)]: Same check but only for the
	   sequence number of the inode
	*/
    } = 1;
} = 0x8000e004;

#endif