STXXL  1.4-dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stxxl::file Class Referenceabstract

Detailed Description

Defines interface of file.

It is a base class for different implementations that might base on various file systems or even remote storage interfaces

Examples:
examples/applications/skew3.cpp, and examples/containers/copy_file.cpp.

Definition at line 56 of file file.h.

+ Inheritance diagram for stxxl::file:
+ Collaboration diagram for stxxl::file:

Public Types

typedef request::offset_type offset_type
 the offset of a request, also the size of the file More...
 
enum  open_mode {
  RDONLY = 1, WRONLY = 2, RDWR = 4, CREAT = 8,
  DIRECT = 16, TRUNC = 32, SYNC = 64, NO_LOCK = 128,
  REQUIRE_DIRECT = 256
}
 Definition of acceptable file open modes. More...
 
typedef request::size_type size_type
 the size of a request More...
 

Public Member Functions

 file (unsigned int device_id=DEFAULT_DEVICE_ID)
 Construct a new file, usually called by a subclass. More...
 
virtual ~file () noexcept(false)
 
void add_request_ref ()
 increment referenced requests More...
 
virtual request_ptr aread (void *buffer, offset_type pos, size_type bytes, const completion_handler &on_cmpl=completion_handler())=0
 Schedules an asynchronous read request to the file. More...
 
virtual request_ptr awrite (void *buffer, offset_type pos, size_type bytes, const completion_handler &on_cmpl=completion_handler())=0
 Schedules an asynchronous write request to the file. More...
 
virtual void close_remove ()
 close and remove file More...
 
void delete_request_ref ()
 decrement referenced requests More...
 
virtual void discard (offset_type offset, offset_type size)
 Discard a region of the file (mark it unused). Some specialized file types may need to know freed regions. More...
 
virtual void export_files (offset_type offset, offset_type length, std::string prefix)
 
virtual int get_allocator_id () const =0
 Returns the file's disk allocator number. More...
 
unsigned int get_device_id () const
 Returns the file's physical device id. More...
 
virtual int get_queue_id () const =0
 Returns the identifier of the file's queue number. More...
 
unsigned_type get_request_nref ()
 return number of referenced requests More...
 
virtual const char * io_type () const =0
 Identifies the type of I/O implementation. More...
 
virtual void lock ()=0
 Locks file for reading and writing (acquires a lock in the file system). More...
 
virtual void serve (void *buffer, offset_type offset, size_type bytes, request::request_type type)=0
 
virtual void set_size (offset_type newsize)=0
 Changes the size of the file. More...
 
virtual offset_type size ()=0
 Returns size of the file. More...
 

Static Public Member Functions

Static Functions for Platform Abstraction
static int unlink (const char *path)
 unlink path from filesystem More...
 
static int truncate (const char *path, external_size_type length)
 truncate a path to given length. Use this only if you dont have a fileio-specific object, which provides truncate(). More...
 

Static Public Attributes

static const unsigned int DEFAULT_DEVICE_ID = (unsigned int)(-1)
 
static const int DEFAULT_LINUXAIO_QUEUE = -2
 
static const int DEFAULT_QUEUE = -1
 
static const int NO_ALLOCATOR = -1
 

Protected Attributes

unsigned int m_device_id
 The file's physical device id (e.g. used for prefetching sequence calculation) More...
 
atomic_counted_object m_request_ref
 count the number of requests referencing this file More...
 

Additional Inherited Members

- Private Member Functions inherited from stxxl::noncopyable
 noncopyable ()
 

Member Typedef Documentation

typedef request::offset_type stxxl::file::offset_type

the offset of a request, also the size of the file

Definition at line 60 of file file.h.

the size of a request

Definition at line 62 of file file.h.

Member Enumeration Documentation

Definition of acceptable file open modes.

Various open modes in a file system must be converted to this set of acceptable modes

Enumerator
RDONLY 

only reading of the file is allowed

WRONLY 

only writing of the file is allowed

RDWR 

read and write of the file are allowed

CREAT 

in case file does not exist no error occurs and file is newly created

DIRECT 

I/Os proceed bypassing file system buffers, i.e.

unbuffered I/O. < Tries to open with appropriate flags, if fails print warning and open normally.

TRUNC 

once file is opened its length becomes zero

SYNC 

open the file with O_SYNC | O_DSYNC | O_RSYNC flags set

NO_LOCK 

do not acquire an exclusive lock by default

REQUIRE_DIRECT 

implies DIRECT, fail if opening with DIRECT flag does not work.

Definition at line 68 of file file.h.

Constructor & Destructor Documentation

stxxl::file::file ( unsigned int  device_id = DEFAULT_DEVICE_ID)
inline

Construct a new file, usually called by a subclass.

Definition at line 88 of file file.h.

virtual stxxl::file::~file ( )
inlinevirtualnoexcept

Definition at line 154 of file file.h.

References STXXL_ERRMSG.

Member Function Documentation

void stxxl::file::add_request_ref ( )
inline

increment referenced requests

Definition at line 186 of file file.h.

Referenced by stxxl::request::request().

virtual request_ptr stxxl::file::aread ( void *  buffer,
offset_type  pos,
size_type  bytes,
const completion_handler on_cmpl = completion_handler() 
)
pure virtual

Schedules an asynchronous read request to the file.

Parameters
bufferpointer to memory buffer to read into
posfile position to start read from
bytesnumber of bytes to transfer
on_cmplI/O completion handler
Returns
request_ptr request object, which can be used to track the status of the operation

Referenced by stxxl::typed_block< RawSize, Type, NRef, MetaInfoType >::read().

virtual request_ptr stxxl::file::awrite ( void *  buffer,
offset_type  pos,
size_type  bytes,
const completion_handler on_cmpl = completion_handler() 
)
pure virtual

Schedules an asynchronous write request to the file.

Parameters
bufferpointer to memory buffer to write from
posstarting file position to write
bytesnumber of bytes to transfer
on_cmplI/O completion handler
Returns
request_ptr request object, which can be used to track the status of the operation

Referenced by stxxl::typed_block< RawSize, Type, NRef, MetaInfoType >::write().

virtual void stxxl::file::close_remove ( )
inlinevirtual

close and remove file

Reimplemented in stxxl::wfs_file_base, and stxxl::ufs_file_base.

Definition at line 152 of file file.h.

void stxxl::file::delete_request_ref ( )
inline

decrement referenced requests

Definition at line 192 of file file.h.

virtual void stxxl::file::discard ( offset_type  offset,
offset_type  size 
)
inlinevirtual

Discard a region of the file (mark it unused). Some specialized file types may need to know freed regions.

Definition at line 137 of file file.h.

References stxxl::STXXL_UNUSED().

virtual void stxxl::file::export_files ( offset_type  offset,
offset_type  length,
std::string  prefix 
)
inlinevirtual

Definition at line 143 of file file.h.

References stxxl::STXXL_UNUSED().

virtual int stxxl::file::get_allocator_id ( ) const
pure virtual

Returns the file's disk allocator number.

Implemented in stxxl::disk_queued_file.

Referenced by stxxl::block_manager::delete_block(), and stxxl::serving_request::serve().

unsigned int stxxl::file::get_device_id ( ) const
inline

Returns the file's physical device id.

Definition at line 175 of file file.h.

virtual int stxxl::file::get_queue_id ( ) const
pure virtual

Returns the identifier of the file's queue number.

Remarks
Files allocated on the same physical device usually share the same queue, unless there is a common queue (e.g. with linuxaio).

Implemented in stxxl::disk_queued_file.

unsigned_type stxxl::file::get_request_nref ( )
inline

return number of referenced requests

Definition at line 198 of file file.h.

virtual const char* stxxl::file::io_type ( ) const
pure virtual

Identifies the type of I/O implementation.

Returns
pointer to null terminated string of characters, containing the name of I/O implementation

Implemented in stxxl::sim_disk_file, stxxl::wbtl_file, stxxl::fileperblock_file< base_file_type >, stxxl::linuxaio_file, stxxl::wincall_file, stxxl::mem_file, stxxl::wfs_file_base, stxxl::mmap_file, stxxl::ufs_file_base, and stxxl::syscall_file.

Referenced by stxxl::request::check_nref_failed(), stxxl::serving_request::io_type(), and stxxl::request::io_type().

virtual void stxxl::file::lock ( )
pure virtual

Locks file for reading and writing (acquires a lock in the file system).

Implemented in stxxl::wbtl_file, stxxl::fileperblock_file< base_file_type >, stxxl::mem_file, stxxl::wfs_file_base, and stxxl::ufs_file_base.

virtual void stxxl::file::serve ( void *  buffer,
offset_type  offset,
size_type  bytes,
request::request_type  type 
)
pure virtual
virtual void stxxl::file::set_size ( offset_type  newsize)
pure virtual

Changes the size of the file.

Parameters
newsizenew file size

Referenced by stxxl::vector< ValueType >::vector().

virtual offset_type stxxl::file::size ( )
pure virtual

Returns size of the file.

Returns
file size in bytes

Implemented in stxxl::wbtl_file, stxxl::fileperblock_file< base_file_type >, stxxl::mem_file, stxxl::wfs_file_base, and stxxl::ufs_file_base.

static int stxxl::file::truncate ( const char *  path,
external_size_type  length 
)
static

truncate a path to given length. Use this only if you dont have a fileio-specific object, which provides truncate().

int stxxl::file::unlink ( const char *  path)
static

unlink path from filesystem

Definition at line 18 of file file.cpp.

Member Data Documentation

const unsigned int stxxl::file::DEFAULT_DEVICE_ID = (unsigned int)(-1)
static

Definition at line 85 of file file.h.

Referenced by stxxl::disk_config::fileio_string(), and stxxl::disk_config::parse_line().

const int stxxl::file::DEFAULT_LINUXAIO_QUEUE = -2
static

Definition at line 83 of file file.h.

Referenced by stxxl::disk_config::fileio_string().

const int stxxl::file::DEFAULT_QUEUE = -1
static

Definition at line 82 of file file.h.

Referenced by stxxl::disk_config::fileio_string(), and stxxl::disk_config::parse_line().

unsigned int stxxl::file::m_device_id
protected

The file's physical device id (e.g. used for prefetching sequence calculation)

Definition at line 171 of file file.h.

atomic_counted_object stxxl::file::m_request_ref
protected

count the number of requests referencing this file

Definition at line 182 of file file.h.

const int stxxl::file::NO_ALLOCATOR = -1
static

Definition at line 84 of file file.h.


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