STXXL  1.4-dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
file.h
Go to the documentation of this file.
1 /***************************************************************************
2  * include/stxxl/bits/io/file.h
3  *
4  * Part of the STXXL. See http://stxxl.sourceforge.net
5  *
6  * Copyright (C) 2002 Roman Dementiev <[email protected]>
7  * Copyright (C) 2008, 2010 Andreas Beckmann <[email protected]>
8  * Copyright (C) 2008, 2009 Johannes Singler <[email protected]>
9  * Copyright (C) 2013-2014 Timo Bingmann <[email protected]>
10  *
11  * Distributed under the Boost Software License, Version 1.0.
12  * (See accompanying file LICENSE_1_0.txt or copy at
13  * http://www.boost.org/LICENSE_1_0.txt)
14  **************************************************************************/
15 
16 #ifndef STXXL_IO_FILE_HEADER
17 #define STXXL_IO_FILE_HEADER
18 
19 #include <stxxl/bits/config.h>
20 
21 #if defined (__linux__)
22  #define STXXL_CHECK_BLOCK_ALIGNING
23 #endif
24 
25 #include <cassert>
26 #include <ostream>
27 #include <string>
28 
32 #include <stxxl/bits/io/request.h>
34 #include <stxxl/bits/libstxxl.h>
35 #include <stxxl/bits/namespace.h>
36 #include <stxxl/bits/noncopyable.h>
37 #include <stxxl/bits/unused.h>
38 #include <stxxl/bits/verbose.h>
39 
41 
42 //! \addtogroup iolayer
43 //! \{
44 
45 //! \defgroup fileimpl File I/O Implementations
46 //! Implementations of \c stxxl::file for various file access methods and
47 //! operating systems.
48 //! \{
49 
50 class completion_handler;
51 
52 //! Defines interface of file.
53 //!
54 //! It is a base class for different implementations that might
55 //! base on various file systems or even remote storage interfaces
56 class file : private noncopyable
57 {
58 public:
59  //! the offset of a request, also the size of the file
60  typedef request::offset_type offset_type;
61  //! the size of a request
63 
64  //! Definition of acceptable file open modes.
65  //!
66  //! Various open modes in a file system must be
67  //! converted to this set of acceptable modes
68  enum open_mode
69  {
70  RDONLY = 1, //!< only reading of the file is allowed
71  WRONLY = 2, //!< only writing of the file is allowed
72  RDWR = 4, //!< read and write of the file are allowed
73  CREAT = 8, //!< in case file does not exist no error occurs and file is newly created
74  DIRECT = 16, //!< I/Os proceed bypassing file system buffers, i.e. unbuffered I/O.
75  //!< Tries to open with appropriate flags, if fails print warning and open normally.
76  TRUNC = 32, //!< once file is opened its length becomes zero
77  SYNC = 64, //!< open the file with O_SYNC | O_DSYNC | O_RSYNC flags set
78  NO_LOCK = 128, //!< do not acquire an exclusive lock by default
79  REQUIRE_DIRECT = 256 //!< implies DIRECT, fail if opening with DIRECT flag does not work.
80  };
81 
82  static const int DEFAULT_QUEUE = -1;
83  static const int DEFAULT_LINUXAIO_QUEUE = -2;
84  static const int NO_ALLOCATOR = -1;
85  static const unsigned int DEFAULT_DEVICE_ID = (unsigned int)(-1);
86 
87  //! Construct a new file, usually called by a subclass.
88  file(unsigned int device_id = DEFAULT_DEVICE_ID)
89  : m_device_id(device_id)
90  { }
91 
92  //! Schedules an asynchronous read request to the file.
93  //! \param buffer pointer to memory buffer to read into
94  //! \param pos file position to start read from
95  //! \param bytes number of bytes to transfer
96  //! \param on_cmpl I/O completion handler
97  //! \return \c request_ptr request object, which can be used to track the
98  //! status of the operation
99 
100  virtual request_ptr aread(void* buffer, offset_type pos, size_type bytes,
101  const completion_handler& on_cmpl = completion_handler()) = 0;
102 
103  //! Schedules an asynchronous write request to the file.
104  //! \param buffer pointer to memory buffer to write from
105  //! \param pos starting file position to write
106  //! \param bytes number of bytes to transfer
107  //! \param on_cmpl I/O completion handler
108  //! \return \c request_ptr request object, which can be used to track the
109  //! status of the operation
110  virtual request_ptr awrite(void* buffer, offset_type pos, size_type bytes,
111  const completion_handler& on_cmpl = completion_handler()) = 0;
112 
113  virtual void serve(void* buffer, offset_type offset, size_type bytes,
114  request::request_type type) = 0;
115 
116  //! Changes the size of the file.
117  //! \param newsize new file size
118  virtual void set_size(offset_type newsize) = 0;
119 
120  //! Returns size of the file.
121  //! \return file size in bytes
122  virtual offset_type size() = 0;
123 
124  //! Returns the identifier of the file's queue number.
125  //! \remark Files allocated on the same physical device usually share the
126  //! same queue, unless there is a common queue (e.g. with linuxaio).
127  virtual int get_queue_id() const = 0;
128 
129  //! Returns the file's disk allocator number
130  virtual int get_allocator_id() const = 0;
131 
132  //! Locks file for reading and writing (acquires a lock in the file system).
133  virtual void lock() = 0;
134 
135  //! Discard a region of the file (mark it unused).
136  //! Some specialized file types may need to know freed regions
137  virtual void discard(offset_type offset, offset_type size)
138  {
139  STXXL_UNUSED(offset);
140  STXXL_UNUSED(size);
141  }
142 
143  virtual void export_files(offset_type offset, offset_type length,
144  std::string prefix)
145  {
146  STXXL_UNUSED(offset);
147  STXXL_UNUSED(length);
148  STXXL_UNUSED(prefix);
149  }
150 
151  //! close and remove file
152  virtual void close_remove() { }
153 
154  virtual ~file() noexcept(false)
155  {
156  unsigned_type nr = get_request_nref();
157  if (nr != 0)
158  STXXL_ERRMSG("stxxl::file is being deleted while there are "
159  "still " << nr << " (unfinished) requests "
160  "referencing it");
161  }
162 
163  //! Identifies the type of I/O implementation.
164  //! \return pointer to null terminated string of characters, containing the
165  //! name of I/O implementation
166  virtual const char * io_type() const = 0;
167 
168 protected:
169  //! The file's physical device id (e.g. used for prefetching sequence
170  //! calculation)
171  unsigned int m_device_id;
172 
173 public:
174  //! Returns the file's physical device id
175  unsigned int get_device_id() const
176  {
177  return m_device_id;
178  }
179 
180 protected:
181  //! count the number of requests referencing this file
183 
184 public:
185  //! increment referenced requests
187  {
188  m_request_ref.inc_reference();
189  }
190 
191  //! decrement referenced requests
193  {
194  m_request_ref.dec_reference();
195  }
196 
197  //! return number of referenced requests
199  {
200  return m_request_ref.get_reference_count();
201  }
202 
203 public:
204  //! \name Static Functions for Platform Abstraction
205  //! \{
206 
207  //! unlink path from filesystem
208  static int unlink(const char* path);
209 
210  //! truncate a path to given length. Use this only if you dont have a
211  //! fileio-specific object, which provides truncate().
212  static int truncate(const char* path, external_size_type length);
213 
214  //! \}
215 };
216 
217 //! \}
218 
219 //! \defgroup reqlayer I/O Requests and Queues
220 //! Encapsulation of an I/O request, queues for requests and threads to process
221 //! them.
222 //! \{
223 //! \}
224 
225 //! \}
226 
228 
229 #endif // !STXXL_IO_FILE_HEADER
230 // vim: et:ts=4:sw=4
unsigned int get_device_id() const
Returns the file&#39;s physical device id.
Definition: file.h:175
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 reg...
Definition: file.h:137
atomic_counted_object m_request_ref
count the number of requests referencing this file
Definition: file.h:182
Completion handler class (Loki-style).
file(unsigned int device_id=DEFAULT_DEVICE_ID)
Construct a new file, usually called by a subclass.
Definition: file.h:88
unsigned_type get_request_nref()
return number of referenced requests
Definition: file.h:198
Provides reference counting abilities for use with counting_ptr with mutex locking.
Definition: counting_ptr.h:461
High-performance smart pointer used as a wrapping reference counting pointer.
Definition: counting_ptr.h:50
request::size_type size_type
the size of a request
Definition: file.h:62
Defines interface of file.
Definition: file.h:56
#define STXXL_BEGIN_NAMESPACE
Definition: namespace.h:16
void STXXL_UNUSED(const U &)
Definition: unused.h:22
virtual void export_files(offset_type offset, offset_type length, std::string prefix)
Definition: file.h:143
open_mode
Definition of acceptable file open modes.
Definition: file.h:68
void add_request_ref()
increment referenced requests
Definition: file.h:186
stxxl::internal_size_type size_type
#define STXXL_ERRMSG(x)
Definition: verbose.h:94
uint64 external_size_type
Definition: types.h:67
choose_int_types< my_pointer_size >::unsigned_type unsigned_type
Definition: types.h:64
static const size_t bytes
number of bytes in uint_pair
Definition: uint_types.h:96
unsigned int m_device_id
The file&#39;s physical device id (e.g. used for prefetching sequence calculation)
Definition: file.h:171
request::offset_type offset_type
the offset of a request, also the size of the file
Definition: file.h:60
virtual void close_remove()
close and remove file
Definition: file.h:152
virtual ~file() noexcept(false)
Definition: file.h:154
void delete_request_ref()
decrement referenced requests
Definition: file.h:192
#define STXXL_END_NAMESPACE
Definition: namespace.h:17