#include "file_system.h"

Inheritance diagram for net_instaweb::FileSystem:

Classes
struct	DirInfo

class	File

struct	FileInfo

class	InputFile

class	NullProgressNotifier

class	OutputFile

class	ProgressNotifier

Public Member Functions
virtual int	MaxPathLength (const StringPiece &base) const

virtual bool	ReadFile (const char filename, int64 max_file_size, Writer writer, MessageHandler *handler)

virtual bool	ReadFile (InputFile input_file, int64 max_file_size, Writer writer, MessageHandler *handler)

virtual bool	ReadFile (const char filename, int64 max_file_size, GoogleString buffer, MessageHandler *handler)

virtual bool	ReadFile (InputFile input_file, int64 max_file_size, GoogleString buffer, MessageHandler *handler)

virtual bool	ReadFile (const char filename, GoogleString buffer, MessageHandler *handler)

virtual bool	ReadFile (InputFile input_file, GoogleString buffer, MessageHandler *handler)

virtual bool	ReadFile (const char filename, Writer writer, MessageHandler *handler)

virtual bool	ReadFile (InputFile input_file, Writer writer, MessageHandler *handler)

virtual bool	WriteFile (const char filename, const StringPiece &buffer, MessageHandler handler)
	Non-atomic. Use WriteFileAtomic() for atomic version.

virtual bool	WriteTempFile (const StringPiece &prefix_name, const StringPiece &buffer, GoogleString filename, MessageHandler handler)

bool	WriteFileAtomic (const StringPiece &filename, const StringPiece &buffer, MessageHandler *handler)

virtual InputFile *	OpenInputFile (const char filename, MessageHandler handler)=0

OutputFile *	OpenOutputFile (const char filename, MessageHandler handler)
	Automatically creates sub-directories to filename.

OutputFile *	OpenOutputFileForAppend (const char filename, MessageHandler handler)

OutputFile *	OpenTempFile (const StringPiece &prefix_name, MessageHandler *handler)

virtual bool	Close (File file, MessageHandler handler)
	Closes the File and cleans up memory.

virtual bool	RemoveFile (const char filename, MessageHandler handler)=0
	Like POSIX 'rm'.

bool	RenameFile (const char old_filename, const char new_filename, MessageHandler *handler)

virtual bool	MakeDir (const char directory_path, MessageHandler handler)=0

virtual bool	RemoveDir (const char directory_path, MessageHandler handler)=0
	Like POSIX 'rmdir', remove a directory only if it is empty.

virtual BoolOrError	Exists (const char path, MessageHandler handler)=0
	Like POSIX 'test -e', checks if path exists (is a file, directory, etc.).

virtual BoolOrError	IsDir (const char path, MessageHandler handler)=0
	Like POSIX 'test -d', checks if path exists and refers to a directory.

virtual bool	RecursivelyMakeDir (const StringPiece &directory_path, MessageHandler *handler)

virtual bool	ListContents (const StringPiece &dir, StringVector files, MessageHandler handler)=0

virtual bool	Atime (const StringPiece &path, int64 timestamp_sec, MessageHandler handler)=0

virtual bool	Mtime (const StringPiece &path, int64 timestamp_sec, MessageHandler handler)=0
	Modified time. Time the file contents were modified.

void	GetDirInfo (const StringPiece &path, DirInfo dirinfo, MessageHandler handler)

virtual void	GetDirInfoWithProgress (const StringPiece &path, DirInfo dirinfo, ProgressNotifier notifier, MessageHandler *handler)

virtual bool	Size (const StringPiece &path, int64 size, MessageHandler handler) const =0

virtual BoolOrError	TryLock (const StringPiece &lock_name, MessageHandler *handler)=0

virtual BoolOrError	TryLockWithTimeout (const StringPiece &lock_name, int64 timeout_millis, const Timer timer, MessageHandler handler)

virtual bool	BumpLockTimeout (const StringPiece &lock_name, MessageHandler *handler)

virtual bool	Unlock (const StringPiece &lock_name, MessageHandler *handler)=0

Static Public Attributes
static const int64	kUnlimitedSize = -1
	This is documented as -1 in user-facing documentation, so don't change it.

Protected Member Functions
virtual OutputFile *	OpenOutputFileHelper (const char filename, bool append, MessageHandler handler)=0

virtual OutputFile *	OpenTempFileHelper (const StringPiece &filename, MessageHandler *handler)=0

virtual bool	RenameFileHelper (const char old_filename, const char new_filename, MessageHandler *handler)=0

Detailed Description

Provides abstract file system interface. This isolation layer helps us:

write unit tests that don't test the physical filesystem via a MemFileSystem.
Eases integration with Apache, which has its own file system interface, and this class can help serve as the glue.
provides a speculative conduit to a database so we can store resources in a place where multiple Apache servers can see them.

Member Function Documentation

virtual bool net_instaweb::FileSystem::Atime	(	const StringPiece &	path,
		int64 *	timestamp_sec,
		MessageHandler *	handler
	)

pure virtual

Stores in *timestamp_sec the timestamp (in seconds since the epoch) of the last time the file was accessed (through one of our Read methods, or by someone else accessing the filesystem directly). Returns true on success, false on failure.

Todo:: TODO(abliss): replace this with a single Stat() function.

Implemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

virtual bool net_instaweb::FileSystem::BumpLockTimeout	(	const StringPiece &	lock_name,
		MessageHandler *	handler
	)

inlinevirtual

If you're holding a lock for a long running task you want to avoid someone else receiving the lock if they request it with TryLockWithTimeout because you've been working for longer than the timeout, you should bump it often enough that it doesn't expire.

Default implementation does nothing, since the default implementation of TryLockWithTimeout doesn't do anything either.

Reimplemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

void net_instaweb::FileSystem::GetDirInfo	(	const StringPiece &	path,
		DirInfo *	dirinfo,
		MessageHandler *	handler
	)

Given a directory path, list the files in the directory and all subdirectories along with total size, inode count, and list of empty directories (useful for cache cleaning). The files/directories in the 'files' and 'empty_dirs' members of dirinfo will have the 'path' input parameter prepended to them. We assume no circular links. If the files or directories are modified while we traverse, we are not guaranteed to represent their final state. The path name should NOT end in a "/".

Todo:: TODO(abliss): unify all slash-ending assumptions

virtual void net_instaweb::FileSystem::GetDirInfoWithProgress	(	const StringPiece &	path,
		DirInfo *	dirinfo,
		ProgressNotifier *	notifier,
		MessageHandler *	handler
	)

virtual

Like GetDirInfo, but notifier->Notify() is called repeatedly as long as GetDirInfo is making progress.

virtual bool net_instaweb::FileSystem::ListContents	(	const StringPiece &	dir,
		StringVector *	files,
		MessageHandler *	handler
	)

pure virtual

Like POSIX 'ls -a', lists all files and directories under the given directory (but omits "." and ".."). Full paths (not just filenames) will be pushed onto the back of the supplied vector (without clearing it). Returns true on success (even if the dir was empty), false on error (even if some files were pushed onto the vector). This is generally not threadsafe! Use a mutex.

Implemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

virtual bool net_instaweb::FileSystem::MakeDir	(	const char *	directory_path,
		MessageHandler *	handler
	)

pure virtual

Like POSIX 'mkdir', makes a directory only if parent directory exists. Fails if directory_name already exists or parent directory doesn't exist.

Implemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

virtual int net_instaweb::FileSystem::MaxPathLength ( const StringPiece & base ) const

virtual

Returns the maximum possible length of a path in a given directory. Note that this is the total, and there may be further constraints on each level. It also depends on the base path.

Default implementation defensively returns 8192.

Reimplemented in net_instaweb::StdioFileSystem.

OutputFile* net_instaweb::FileSystem::OpenOutputFileForAppend	(	const char *	filename,
		MessageHandler *	handler
	)

inline

Open a file to append to it. Automatically creates sub-directories to filename.

virtual OutputFile* net_instaweb::FileSystem::OpenOutputFileHelper	(	const char *	filename,
		bool	append,
		MessageHandler *	handler
	)

protectedpure virtual

These interfaces must be defined by implementers of FileSystem. They may assume the directory already exists.

Implemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

OutputFile* net_instaweb::FileSystem::OpenTempFile	(	const StringPiece &	prefix_name,
		MessageHandler *	handler
	)

inline

Opens a temporary file to write, with the specified prefix. If successful, the filename can be obtained from File::filename(). Automatically creates sub-directories to filename.

NULL is returned on failure.

virtual bool net_instaweb::FileSystem::ReadFile	(	const char *	filename,
		int64	max_file_size,
		Writer *	writer,
		MessageHandler *	handler
	)

virtual

High level support to read/write entire files in one shot. The input_file versions accept a NULL input_file, in which case they report failure. If the file is larget than max_file_size, return false. All routines close the file.

virtual bool net_instaweb::FileSystem::ReadFile	(	const char *	filename,
		GoogleString *	buffer,
		MessageHandler *	handler
	)

virtual

Deprecated versions of ReadFile, because they can OOM if the file they're trying to read happens to be surprisingly large. Instead, call ReadFile with a limit. If you can guarantee that you'll never encounter a large file with this call, perhaps because you're reading a file you created, then call ReadFile with an explicit limit of kUnlimitedSize.

virtual bool net_instaweb::FileSystem::RecursivelyMakeDir	(	const StringPiece &	directory_path,
		MessageHandler *	handler
	)

virtual

Like POSIX 'mkdir -p', makes all directories up to this one recursively. Fails if we do not have permission to make any directory in chain.

Reimplemented in net_instaweb::MemFileSystem.

bool net_instaweb::FileSystem::RenameFile	(	const char *	old_filename,
		const char *	new_filename,
		MessageHandler *	handler
	)

inline

Like POSIX 'mv', except it automatically creates sub-directories for new_filename.

virtual bool net_instaweb::FileSystem::Size	(	const StringPiece &	path,
		int64 *	size,
		MessageHandler *	handler
	)		const

pure virtual

Given a file, computes its size in bytes and store it in *size. Returns true on success, false on failure. Behavior is undefined if path refers to a directory. This function has different behavior depending on the underlying implementation. Memory-based implementations will report the size of the file, while disk-based implementations should return the actual allocated size on disk.

Todo:: TODO(abliss): replace this with a single Stat() function.

Implemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

virtual BoolOrError net_instaweb::FileSystem::TryLock	(	const StringPiece &	lock_name,
		MessageHandler *	handler
	)

pure virtual

Attempts to obtain a global (cross-process, cross-thread) lock of the given name (which should be a valid filename, not otherwise used, in an extant directory). If someone else has this lock, returns False immediately. If anything goes wrong, returns Error. On success, returns True: then you must call Unlock when you are done.

Implemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

virtual BoolOrError net_instaweb::FileSystem::TryLockWithTimeout	(	const StringPiece &	lock_name,
		int64	timeout_millis,
		const Timer *	timer,
		MessageHandler *	handler
	)

inlinevirtual

Like TryLock, but may attempt to break stale locks, though the default implementation never actually breaks any. A lock is stale if it was taken (or last bumped) more than timeout_millis ms ago.

If you obtain a lock through this method, there are no hard guarantees that nobody else has it too. <blink> If you use this function, your lock becomes "best-effort". </blink>

If you override this function, you need to override BumpLockTimeout as well.

Reimplemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

virtual bool net_instaweb::FileSystem::Unlock	(	const StringPiece &	lock_name,
		MessageHandler *	handler
	)

pure virtual

Attempts to release a lock previously obtained through TryLock. If your thread did not previously obtain the lock, the behavior is undefined. Returns true if we successfully release the lock. Returns false if we were unable to release the lock (e.g. somebody came along and write-protected the lockfile). You might try again, or start using a different lock name.

Implemented in net_instaweb::MemFileSystem, and net_instaweb::StdioFileSystem.

bool net_instaweb::FileSystem::WriteFileAtomic	(	const StringPiece &	filename,
		const StringPiece &	buffer,
		MessageHandler *	handler
	)

Write a temp file first and then copy to filename so that the file cannot be read after being partially written. Temp file name is based on filename.

virtual bool net_instaweb::FileSystem::WriteTempFile	(	const StringPiece &	prefix_name,
		const StringPiece &	buffer,
		GoogleString *	filename,
		MessageHandler *	handler
	)

virtual

Writes given data to a temp file in one shot, storing the filename in filename on success. Returns false and clears filename on failure.

Reimplemented in net_instaweb::MemFileSystem.

The documentation for this class was generated from the following file:

pagespeed/kernel/base/file_system.h

Classes

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Function Documentation