Seastar
High performance C++ framework for concurrent servers
fstream.hh
Go to the documentation of this file.
1 /*
2  * This file is open source software, licensed to you under the terms
3  * of the Apache License, Version 2.0 (the "License"). See the NOTICE file
4  * distributed with this work for additional information regarding copyright
5  * ownership. You may not use this file except in compliance with the License.
6  *
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing,
12  * software distributed under the License is distributed on an
13  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14  * KIND, either express or implied. See the License for the
15  * specific language governing permissions and limitations
16  * under the License.
17  */
18 /*
19  * Copyright (C) 2015 Cloudius Systems, Ltd.
20  */
21 
22 #pragma once
23 
25 
26 // File <-> streams adapters
27 //
28 // Seastar files are block-based due to the reliance on DMA - you must read
29 // on sector boundaries. The adapters in this file provide a byte stream
30 // interface to files, while retaining the zero-copy characteristics of
31 // seastar files.
32 
33 #include <seastar/core/file.hh>
34 #include <seastar/core/iostream.hh>
35 #include <seastar/core/shared_ptr.hh>
36 #include <seastar/core/internal/api-level.hh>
37 
38 namespace seastar {
39 
41  static constexpr uint64_t window_size = 4 * 1024 * 1024;
42  struct window {
43  uint64_t total_read = 0;
44  uint64_t unused_read = 0;
45  };
46  window current_window;
47  window previous_window;
48  unsigned read_ahead = 1;
49 
50  friend class file_data_source_impl;
51 };
52 
55  size_t buffer_size = 8192;
56  unsigned read_ahead = 0;
57  ::seastar::io_priority_class io_priority_class = default_priority_class();
59 };
60 
70 input_stream<char> make_file_input_stream(
71  file file, uint64_t offset, uint64_t len, file_input_stream_options options = {});
72 
73 // Create an input_stream for a given file, with the specified options.
74 // Multiple fibers of execution (continuations) may safely open
75 // multiple input streams concurrently for the same file.
76 input_stream<char> make_file_input_stream(
77  file file, uint64_t offset, file_input_stream_options = {});
78 
79 // Create an input_stream for reading starting at a given position of the
80 // given file. Multiple fibers of execution (continuations) may safely open
81 // multiple input streams concurrently for the same file.
82 input_stream<char> make_file_input_stream(
83  file file, file_input_stream_options = {});
84 
86  // For small files, setting preallocation_size can make it impossible for XFS to find
87  // an aligned extent. On the other hand, without it, XFS will divide the file into
88  // file_size/buffer_size extents. To avoid fragmentation, we set the default buffer_size
89  // to 64k (so each extent will be a minimum of 64k) and preallocation_size to 0 (to avoid
90  // extent allocation problems).
91  //
92  // Large files should increase both buffer_size and preallocation_size.
93  unsigned buffer_size = 65536;
94  unsigned preallocation_size = 0;
95  unsigned write_behind = 1;
96  ::seastar::io_priority_class io_priority_class = default_priority_class();
97 };
98 
99 SEASTAR_INCLUDE_API_V2 namespace api_v2 {
100 
104 [[deprecated("use Seastar_API_LEVEL=3 instead")]]
105 output_stream<char> make_file_output_stream(
106  file file,
107  uint64_t buffer_size = 8192);
108 
112 [[deprecated("use Seastar_API_LEVEL=3 instead")]]
113 output_stream<char> make_file_output_stream(
114  file file,
116 
119 [[deprecated("use Seastar_API_LEVEL=3 instead")]]
120 data_sink make_file_data_sink(file, file_output_stream_options);
121 
122 }
123 
124 SEASTAR_INCLUDE_API_V3 namespace api_v3 {
125 inline namespace and_newer {
126 
131 future<output_stream<char>> make_file_output_stream(
132  file file,
133  uint64_t buffer_size = 8192) noexcept;
134 
139 future<output_stream<char>> make_file_output_stream(
140  file file,
141  file_output_stream_options options) noexcept;
142 
146 future<data_sink> make_file_data_sink(file, file_output_stream_options) noexcept;
147 
148 }
149 }
150 
151 }
seastar::file_output_stream_options::write_behind
unsigned write_behind
Number of buffers to write in parallel.
Definition: fstream.hh:95
seastar
Seastar API namespace.
Definition: abort_on_ebadf.hh:24
seastar::file_input_stream_options::read_ahead
unsigned read_ahead
Maximum number of extra read-ahead operations.
Definition: fstream.hh:56
seastar::lw_shared_ptr
Definition: shared_ptr.hh:62
seastar::file_output_stream_options::preallocation_size
unsigned preallocation_size
Preallocate extents. For large files, set to a large number (a few megabytes) to reduce fragmentation...
Definition: fstream.hh:94
seastar::file_input_stream_options::buffer_size
size_t buffer_size
I/O buffer size.
Definition: fstream.hh:55
seastar::file_output_stream_options
Definition: fstream.hh:85
seastar::make_file_input_stream
input_stream< char > make_file_input_stream(file file, uint64_t offset, uint64_t len, file_input_stream_options options={})
Creates an input_stream to read a portion of a file.
seastar::file_input_stream_options
Data structure describing options for opening a file input stream.
Definition: fstream.hh:54
seastar::output_stream< char >
seastar::file_input_stream_history
Definition: fstream.hh:40
seastar::file
Definition: file.hh:158
seastar::file_input_stream_options::dynamic_adjustments
lw_shared_ptr< file_input_stream_history > dynamic_adjustments
Input stream history, if null dynamic adjustments are disabled.
Definition: fstream.hh:58
seastar::data_sink
Definition: iostream.hh:93