Thrill  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
file.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * foxxll/io/file.hpp
3  *
4  * Part of FOXXLL. See http://foxxll.org
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 FOXXLL_IO_FILE_HEADER
17 #define FOXXLL_IO_FILE_HEADER
18 
19 #include <cassert>
20 #include <limits>
21 #include <ostream>
22 #include <string>
23 
24 #include <tlx/counting_ptr.hpp>
25 #include <tlx/logger/core.hpp>
26 #include <tlx/unused.hpp>
27 
29 #include <foxxll/common/types.hpp>
30 #include <foxxll/config.hpp>
31 #include <foxxll/io/iostats.hpp>
32 #include <foxxll/io/request.hpp>
34 #include <foxxll/libfoxxll.hpp>
35 
36 #if defined(__linux__)
37  #define FOXXLL_CHECK_BLOCK_ALIGNING
38 #endif
39 
40 namespace foxxll {
41 
42 //! \addtogroup foxxll_iolayer
43 //! \{
44 
45 //! \defgroup foxxll_fileimpl File I/O Implementations
46 //! Implementations of \c foxxll::file for various file access methods and
47 //! operating systems.
48 //! \{
49 
50 //! Defines interface of file.
51 //!
52 //! It is a base class for different implementations that might
53 //! base on various file systems or even remote storage interfaces
55 {
56 public:
57  //! the offset of a request, also the size of the file
59  //! the size of a request
61 
62  //! Definition of acceptable file open modes. Various open modes in a file
63  //!system must be converted to this set of acceptable modes
64  enum open_mode
65  {
66  //! only reading of the file is allowed
67  RDONLY = 1,
68  //! only writing of the file is allowed
69  WRONLY = 2,
70  //! read and write of the file are allowed
71  RDWR = 4,
72  //! in case file does not exist no error occurs and file is newly
73  //! created
74  CREAT = 8,
75  //! I/Os proceed bypassing file system buffers, i.e. unbuffered I/O.
76  //! Tries to open with appropriate flags, if fails print warning and
77  //! open normally.
78  DIRECT = 16,
79  //! once file is opened its length becomes zero
80  TRUNC = 32,
81  //! open the file with O_SYNC | O_DSYNC | O_RSYNC flags set
82  SYNC = 64,
83  //! do not acquire an exclusive lock by default
84  NO_LOCK = 128,
85  //! implies DIRECT, fail if opening with DIRECT flag does not work.
87  };
88 
89  static const int DEFAULT_QUEUE = -1;
90  static const int DEFAULT_LINUXAIO_QUEUE = -2;
91  static const int NO_ALLOCATOR = -1;
93 
94  //! Construct a new file, usually called by a subclass.
95  explicit file(unsigned int device_id = DEFAULT_DEVICE_ID,
96  file_stats* file_stats = nullptr)
97  : device_id_(device_id),
98  file_stats_(file_stats != nullptr ? file_stats
99  : stats::get_instance()->create_file_stats(device_id))
100  { }
101 
102  //! non-copyable: delete copy-constructor
103  file(const file&) = delete;
104  //! non-copyable: delete assignment operator
105  file& operator = (const file&) = delete;
106  //! move-constructor: default
107  file(file&&) = default;
108  //! move-assignment operator: default
109  file& operator = (file&&) = default;
110 
111  //! Schedules an asynchronous read request to the file.
112  //! \param buffer pointer to memory buffer to read into
113  //! \param pos file position to start read from
114  //! \param bytes number of bytes to transfer
115  //! \param on_complete I/O completion handler
116  //! \return \c request_ptr request object, which can be used to track the
117  //! status of the operation
118 
119  virtual request_ptr aread(
120  void* buffer, offset_type pos, size_type bytes,
121  const completion_handler& on_complete = completion_handler()) = 0;
122 
123  //! Schedules an asynchronous write request to the file.
124  //! \param buffer pointer to memory buffer to write from
125  //! \param pos starting file position to write
126  //! \param bytes number of bytes to transfer
127  //! \param on_complete I/O completion handler
128  //! \return \c request_ptr request object, which can be used to track the
129  //! status of the operation
130 
131  virtual request_ptr awrite(
132  void* buffer, offset_type pos, size_type bytes,
133  const completion_handler& on_complete = completion_handler()) = 0;
134 
135  virtual void serve(void* buffer, offset_type offset, size_type bytes,
136  request::read_or_write op) = 0;
137 
138  //! Changes the size of the file.
139  //! \param newsize new file size
140  virtual void set_size(offset_type newsize) = 0;
141 
142  //! Returns size of the file.
143  //! \return file size in bytes
144  virtual offset_type size() = 0;
145 
146  //! Returns the identifier of the file's queue number.
147  //! \remark Files allocated on the same physical device usually share the
148  //! same queue, unless there is a common queue (e.g. with linuxaio).
149  virtual int get_queue_id() const = 0;
150 
151  //! Returns the file's parallel disk block allocator number
152  virtual int get_allocator_id() const = 0;
153 
154  //! Locks file for reading and writing (acquires a lock in the file system).
155  virtual void lock() = 0;
156 
157  //! Discard a region of the file (mark it unused).
158  //! Some specialized file types may need to know freed regions
159  virtual void discard(offset_type offset, offset_type size)
160  {
161  tlx::unused(offset);
162  tlx::unused(size);
163  }
164 
165  virtual void export_files(offset_type offset, offset_type length,
166  std::string prefix)
167  {
168  tlx::unused(offset);
169  tlx::unused(length);
170  tlx::unused(prefix);
171  }
172 
173  //! close and remove file
174  virtual void close_remove() { }
175 
176  virtual ~file()
177  {
178  const size_t nr = get_request_nref();
179  if (nr != 0) {
180  TLX_LOG1 << "foxxll::file is being deleted while there are still "
181  << nr << " (unfinished) requests referencing it";
182  }
183  }
184 
185  //! Identifies the type of I/O implementation.
186  //! \return pointer to null terminated string of characters, containing the
187  //! name of I/O implementation
188  virtual const char * io_type() const = 0;
189 
190 protected:
191  //! Flag whether read/write operations REQUIRE alignment
192  bool need_alignment_ = false;
193 
194  //! The file's physical device id (e.g. used for prefetching sequence
195  //! calculation)
196  unsigned int device_id_;
197 
198  //! pointer to file's stats inside of iostats. Because the stats can live
199  //! longer than the file, the iostats keeps ownership.
201 
202 public:
203  //! Returns need_alignment_
204  bool need_alignment() const { return need_alignment_; }
205 
206  //! Returns the file's physical device id
207  unsigned int get_device_id() const
208  {
209  return device_id_;
210  }
211 
213  {
214  return file_stats_;
215  }
216 
217 protected:
218  //! count the number of requests referencing this file
220 
221 public:
222  //! increment referenced requests
224  {
226  }
227 
228  //! decrement referenced requests
230  {
232  }
233 
234  //! return number of referenced requests
236  {
237  return request_ref_.reference_count();
238  }
239 
240 public:
241  //! \name Static Functions for Platform Abstraction
242  //! \{
243 
244  //! unlink path from filesystem
245  static int unlink(const char* path);
246 
247  //! truncate a path to given length. Use this only if you dont have a
248  //! fileio-specific object, which provides truncate().
249  static int truncate(const char* path, external_size_type length);
250 
251  //! \}
252 };
253 
254 //! \}
255 
256 //! \defgroup foxxll_reqlayer I/O Requests and Queues
257 //! Encapsulation of an I/O request, queues for requests and threads to process
258 //! them.
259 //! \{
260 //! \}
261 
262 //! \}
263 
264 //! A reference counting pointer for \c file.
266 
267 } // namespace foxxll
268 
269 #endif // !FOXXLL_IO_FILE_HEADER
270 
271 /**************************************************************************/
virtual void set_size(offset_type newsize)=0
virtual int get_allocator_id() const =0
Returns the file's parallel disk block allocator number.
only reading of the file is allowed
Definition: file.hpp:67
only writing of the file is allowed
Definition: file.hpp:69
uint64_t offset_type
type for offsets within a file
static uint_pair max()
return an uint_pair instance containing the largest value possible
Definition: uint_types.hpp:226
virtual offset_type size()=0
virtual void export_files(offset_type offset, offset_type length, std::string prefix)
Definition: file.hpp:165
static const unsigned int DEFAULT_DEVICE_ID
Definition: file.hpp:92
virtual const char * io_type() const =0
request::offset_type offset_type
the offset of a request, also the size of the file
Definition: file.hpp:58
unsigned int device_id_
Definition: file.hpp:196
file & operator=(const file &)=delete
non-copyable: delete assignment operator
virtual request_ptr awrite(void *buffer, offset_type pos, size_type bytes, const completion_handler &on_complete=completion_handler())=0
do not acquire an exclusive lock by default
Definition: file.hpp:84
size_t size_type
type for block transfer sizes
implies DIRECT, fail if opening with DIRECT flag does not work.
Definition: file.hpp:86
virtual request_ptr aread(void *buffer, offset_type pos, size_type bytes, const completion_handler &on_complete=completion_handler())=0
file_stats * file_stats_
Definition: file.hpp:200
void delete_request_ref()
decrement referenced requests
Definition: file.hpp:229
virtual int get_queue_id() const =0
void unused(Types &&...)
Definition: unused.hpp:20
bool dec_reference() const noexcept
Call whenever resetting (i.e.
tlx::delegate< void(request *r, bool success)> completion_handler
completion handler
Definition: request.hpp:46
request::size_type size_type
the size of a request
Definition: file.hpp:60
bool need_alignment() const
Returns need_alignment_.
Definition: file.hpp:204
virtual void lock()=0
Locks file for reading and writing (acquires a lock in the file system).
virtual void close_remove()
close and remove file
Definition: file.hpp:174
virtual void serve(void *buffer, offset_type offset, size_type bytes, request::read_or_write op)=0
static int truncate(const char *path, external_size_type length)
size_t get_request_nref()
return number of referenced requests
Definition: file.hpp:235
size_t reference_count() const noexcept
Return the number of references to this object (for debugging)
static const int DEFAULT_QUEUE
Definition: file.hpp:89
std::basic_string< char, std::char_traits< char >, Allocator< char > > string
string with Manager tracking
Definition: allocator.hpp:220
tlx::reference_counter request_ref_
count the number of requests referencing this file
Definition: file.hpp:219
High-performance smart pointer used as a wrapping reference counting pointer.
virtual void discard(offset_type offset, offset_type size)
Definition: file.hpp:159
static const size_t bytes
number of bytes in uint_pair
Definition: uint_types.hpp:75
virtual ~file()
Definition: file.hpp:176
void inc_reference() const noexcept
Call whenever setting a pointer to the object.
static const int DEFAULT_LINUXAIO_QUEUE
Definition: file.hpp:90
file(unsigned int device_id=DEFAULT_DEVICE_ID, file_stats *file_stats=nullptr)
Construct a new file, usually called by a subclass.
Definition: file.hpp:95
static const int NO_ALLOCATOR
Definition: file.hpp:91
static int unlink(const char *path)
unlink path from filesystem
Definition: file.cpp:18
#define TLX_LOG1
Definition: core.hpp:145
bool need_alignment_
Flag whether read/write operations REQUIRE alignment.
Definition: file.hpp:192
file_stats * get_file_stats() const
Definition: file.hpp:212
once file is opened its length becomes zero
Definition: file.hpp:80
read and write of the file are allowed
Definition: file.hpp:71
open the file with O_SYNC | O_DSYNC | O_RSYNC flags set
Definition: file.hpp:82
uint64_t external_size_type
Definition: types.hpp:27
void add_request_ref()
increment referenced requests
Definition: file.hpp:223
unsigned int get_device_id() const
Returns the file's physical device id.
Definition: file.hpp:207
Provides reference counting abilities for use with CountingPtr.