AFP Client Caching

This chapter describes how the AFP client in OS X v10.2 and later caches data before sending it to an AFP server.

First, some terms and definitions:

File Data Caching

By default, the AFP client uses the UBC to cache file data, with the following exceptions:

The AFP client checks cache consistency during the following operations:

File Metadata Caching

Each file’s metadata is maintained in a vnode structure for that file. The AFP client should check a file’s metadata for coherency with the server when the AFP client accesses a vnode after the server has sent a Volume Change Attention packet. Each vnode contains a time stamp of the last Volume Change Attention packet that caused this vnode to be updated. If the timestamp of the last received Volume Change Attention is different from the timestamp in this vnode, this vnode’s file metadata must be stale and the AFP client should send a request for the latest information to the server.

Whenever an AFP client needs to use a file’s Modification date or fork size information, it should ask the server for the current information. To prevent the server from being flooded with requests, AFP clients should limit their requests for metadata to one request per second.

In addition, file metadata in the AFP caches has a maximum Time To Live (TTL) value. This TTL is intended to help when two clients have a file open at the same time. Without this timer, if one client writes to the file but never closes it, then a volume change attention packet would never be sent by the server, so the second client would never see the EOF change.

Because of the TTL timer, when the second client checks the EOF, if no volume change attention packet has been received but the TTL timer has expired, the client requests the latest information from the server anyway. This is not really polling, per se, because it only occurs when the vnode is accessed. If the vnode is never accessed, the TTL makes no difference.

Recently modified files are assumed to be more likely to change than files that have not changed in a while. For this reason, the TTL is determined by taking the amount of time since the file was last modified, dividing the value by 10, and limiting the minimum and maximum values.

For example, with the default TTL values of 5 and 60 seconds:

This algorithm is based on NFS metadata caching.

Controlling Caching

There are two ways to disable data caching in the AFP client and access the current data on the server:

Use the noCacheMask flag. See Technical note FL16 for more information on how to use the noCacheMask flag.

Use the fcntl call on the file descriptor, as in the following examples:

(void) fcntl(fd, F_NOCACHE, 1); /* turn off data caching */
(void) fcntl(fd, F_NOCACHE, 0); /* turn on data caching */

Note that even though data caching in the AFP client may be disabled, Carbon may still cache fork information like fork length and current fork position.