The Hummingbird interface

This section describes the basic Hummingbird calls. All routines return a positive integer or zero if the operation succeeds; a negative return value is an error code.

• int write_file(char* fname, void* buf, size_t sz); This function writes the contents of the memory area starting at buf with size sz to the file system with filename fname. It returns the size of the file. Once the pointer buf is handed over to the file system, the application should not use it again. Hummingbird will eventually pack the file into a cluster, free the buffer, and write the cluster to stable storage.

• int read_file(char* fname, void** buf); This function sets *buf to the beginning of the memory area containing the contents of the file fname. It increments a reference count and returns the size of the file. If the file is not in main memory, another file or files may be evicted to make room, and a cluster containing the specified file will be read from disk.

• int done_read_file(char* fname, void* buf); This function releases the space occupied by the file in main memory by decrementing the reference count; the application should not use the pointer again. Every read_file() must be accompanied by a done_read_file(). Otherwise, the file will stay in memory indefinitely (until the application program terminates).

• int delete_file(char* fname); This function deletes the file fname. An error code is returned if the file has any active read_file()'s.

• int collocate_files(char* fnameA, char* fnameB); This function attempts to collocate file fnameB with file fnameA on disk. Both files must be previously written (by calling write_file()).

• int write_nomem_file(char* fname, void* buf, size_t sz); This function bypasses the main memory cache and writes a file directly to disk. This file is flagged so that when it is read, it does not compete with other documents for cache space and is immediately released after the application issues the done_read_file().

Missing from this API are commands such as ls and df. We have seen no need for such commands for a caching web proxy. For example, the existence of a file can be determined with read_file().