1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
2 //  This source code is licensed under both the GPLv2 (found in the
3 //  COPYING file in the root directory) and Apache 2.0 License
4 //  (found in the LICENSE.Apache file in the root directory).
5 
6 package org.rocksdb;
7 
8 import java.util.Map;
9 
10 /**
11  * SstFileManager is used to track SST files in the DB and control their
12  * deletion rate.
13  *
14  * All SstFileManager public functions are thread-safe.
15  *
16  * SstFileManager is not extensible.
17  */
18 //@ThreadSafe
19 public final class SstFileManager extends RocksObject {
20 
21   public static final long RATE_BYTES_PER_SEC_DEFAULT = 0;
22   public static final boolean DELETE_EXISTING_TRASH_DEFAULT = true;
23   public static final double MAX_TRASH_DB_RATION_DEFAULT = 0.25;
24   public static final long BYTES_MAX_DELETE_CHUNK_DEFAULT = 64 * 1024 * 1024;
25 
26   /**
27    * Create a new SstFileManager that can be shared among multiple RocksDB
28    * instances to track SST file and control there deletion rate.
29    *
30    * @param env the environment.
31    *
32    * @throws RocksDBException thrown if error happens in underlying native library.
33    */
SstFileManager(final Env env)34   public SstFileManager(final Env env) throws RocksDBException {
35     this(env, null);
36   }
37 
38   /**
39    * Create a new SstFileManager that can be shared among multiple RocksDB
40    * instances to track SST file and control there deletion rate.
41    *
42    * @param env the environment.
43    * @param logger if not null, the logger will be used to log errors.
44    *
45    * @throws RocksDBException thrown if error happens in underlying native library.
46    */
SstFileManager(final Env env, final Logger logger)47   public SstFileManager(final Env env, /*@Nullable*/  final Logger logger)
48       throws RocksDBException {
49     this(env, logger, RATE_BYTES_PER_SEC_DEFAULT);
50   }
51 
52   /**
53    * Create a new SstFileManager that can be shared among multiple RocksDB
54    * instances to track SST file and control there deletion rate.
55    *
56    * @param env the environment.
57    * @param logger if not null, the logger will be used to log errors.
58    *
59    * == Deletion rate limiting specific arguments ==
60    * @param rateBytesPerSec how many bytes should be deleted per second, If
61    *     this value is set to 1024 (1 Kb / sec) and we deleted a file of size
62    *     4 Kb in 1 second, we will wait for another 3 seconds before we delete
63    *     other files, Set to 0 to disable deletion rate limiting.
64    *
65    * @throws RocksDBException thrown if error happens in underlying native library.
66    */
SstFileManager(final Env env, final Logger logger, final long rateBytesPerSec)67   public SstFileManager(final Env env, /*@Nullable*/  final Logger logger,
68       final long rateBytesPerSec) throws RocksDBException {
69     this(env, logger, rateBytesPerSec, MAX_TRASH_DB_RATION_DEFAULT);
70   }
71 
72   /**
73    * Create a new SstFileManager that can be shared among multiple RocksDB
74    * instances to track SST file and control there deletion rate.
75    *
76    * @param env the environment.
77    * @param logger if not null, the logger will be used to log errors.
78    *
79    * == Deletion rate limiting specific arguments ==
80    * @param rateBytesPerSec how many bytes should be deleted per second, If
81    *     this value is set to 1024 (1 Kb / sec) and we deleted a file of size
82    *     4 Kb in 1 second, we will wait for another 3 seconds before we delete
83    *     other files, Set to 0 to disable deletion rate limiting.
84    * @param maxTrashDbRatio if the trash size constitutes for more than this
85    *     fraction of the total DB size we will start deleting new files passed
86    *     to DeleteScheduler immediately.
87    *
88    *  @throws RocksDBException thrown if error happens in underlying native library.
89    */
SstFileManager(final Env env, final Logger logger, final long rateBytesPerSec, final double maxTrashDbRatio)90   public SstFileManager(final Env env, /*@Nullable*/ final Logger logger,
91       final long rateBytesPerSec, final double maxTrashDbRatio)
92       throws RocksDBException {
93     this(env, logger, rateBytesPerSec, maxTrashDbRatio,
94         BYTES_MAX_DELETE_CHUNK_DEFAULT);
95   }
96 
97   /**
98    * Create a new SstFileManager that can be shared among multiple RocksDB
99    * instances to track SST file and control there deletion rate.
100    *
101    * @param env the environment.
102    * @param logger if not null, the logger will be used to log errors.
103    *
104    * == Deletion rate limiting specific arguments ==
105    * @param rateBytesPerSec how many bytes should be deleted per second, If
106    *     this value is set to 1024 (1 Kb / sec) and we deleted a file of size
107    *     4 Kb in 1 second, we will wait for another 3 seconds before we delete
108    *     other files, Set to 0 to disable deletion rate limiting.
109    * @param maxTrashDbRatio if the trash size constitutes for more than this
110    *     fraction of the total DB size we will start deleting new files passed
111    *     to DeleteScheduler immediately.
112    * @param bytesMaxDeleteChunk if a single file is larger than delete chunk,
113    *     ftruncate the file by this size each time, rather than dropping the whole
114    *     file. 0 means to always delete the whole file.
115    *
116    * @throws RocksDBException thrown if error happens in underlying native library.
117    */
SstFileManager(final Env env, final Logger logger, final long rateBytesPerSec, final double maxTrashDbRatio, final long bytesMaxDeleteChunk)118   public SstFileManager(final Env env, /*@Nullable*/final Logger logger,
119       final long rateBytesPerSec, final double maxTrashDbRatio,
120       final long bytesMaxDeleteChunk) throws RocksDBException {
121     super(newSstFileManager(env.nativeHandle_,
122         logger != null ? logger.nativeHandle_ : 0,
123         rateBytesPerSec, maxTrashDbRatio, bytesMaxDeleteChunk));
124   }
125 
126 
127   /**
128    * Update the maximum allowed space that should be used by RocksDB, if
129    * the total size of the SST files exceeds {@code maxAllowedSpace}, writes to
130    * RocksDB will fail.
131    *
132    * Setting {@code maxAllowedSpace} to 0 will disable this feature;
133    * maximum allowed space will be infinite (Default value).
134    *
135    * @param maxAllowedSpace the maximum allowed space that should be used by
136    *     RocksDB.
137    */
setMaxAllowedSpaceUsage(final long maxAllowedSpace)138   public void setMaxAllowedSpaceUsage(final long maxAllowedSpace) {
139     setMaxAllowedSpaceUsage(nativeHandle_, maxAllowedSpace);
140   }
141 
142   /**
143    * Set the amount of buffer room each compaction should be able to leave.
144    * In other words, at its maximum disk space consumption, the compaction
145    * should still leave {@code compactionBufferSize} available on the disk so
146    * that other background functions may continue, such as logging and flushing.
147    *
148    * @param compactionBufferSize the amount of buffer room each compaction
149    *     should be able to leave.
150    */
setCompactionBufferSize(final long compactionBufferSize)151   public void setCompactionBufferSize(final long compactionBufferSize) {
152     setCompactionBufferSize(nativeHandle_, compactionBufferSize);
153   }
154 
155   /**
156    * Determines if the total size of SST files exceeded the maximum allowed
157    * space usage.
158    *
159    * @return true when the maximum allows space usage has been exceeded.
160    */
isMaxAllowedSpaceReached()161   public boolean isMaxAllowedSpaceReached() {
162     return isMaxAllowedSpaceReached(nativeHandle_);
163   }
164 
165   /**
166    * Determines if the total size of SST files as well as estimated size
167    * of ongoing compactions exceeds the maximums allowed space usage.
168    *
169    * @return true when the total size of SST files as well as estimated size
170    * of ongoing compactions exceeds the maximums allowed space usage.
171    */
isMaxAllowedSpaceReachedIncludingCompactions()172   public boolean isMaxAllowedSpaceReachedIncludingCompactions() {
173     return isMaxAllowedSpaceReachedIncludingCompactions(nativeHandle_);
174   }
175 
176   /**
177    * Get the total size of all tracked files.
178    *
179    * @return the total size of all tracked files.
180    */
getTotalSize()181   public long getTotalSize() {
182     return getTotalSize(nativeHandle_);
183   }
184 
185   /**
186    * Gets all tracked files and their corresponding sizes.
187    *
188    * @return a map containing all tracked files and there corresponding sizes.
189    */
getTrackedFiles()190   public Map<String, Long> getTrackedFiles() {
191     return getTrackedFiles(nativeHandle_);
192   }
193 
194   /**
195    * Gets the delete rate limit.
196    *
197    * @return the delete rate limit (in bytes per second).
198    */
getDeleteRateBytesPerSecond()199   public long getDeleteRateBytesPerSecond() {
200     return getDeleteRateBytesPerSecond(nativeHandle_);
201   }
202 
203   /**
204    * Set the delete rate limit.
205    *
206    * Zero means disable delete rate limiting and delete files immediately.
207    *
208    * @param deleteRate the delete rate limit (in bytes per second).
209    */
setDeleteRateBytesPerSecond(final long deleteRate)210   public void setDeleteRateBytesPerSecond(final long deleteRate) {
211     setDeleteRateBytesPerSecond(nativeHandle_, deleteRate);
212   }
213 
214   /**
215    * Get the trash/DB size ratio where new files will be deleted immediately.
216    *
217    * @return the trash/DB size ratio.
218    */
getMaxTrashDBRatio()219   public double getMaxTrashDBRatio() {
220     return getMaxTrashDBRatio(nativeHandle_);
221   }
222 
223   /**
224    * Set the trash/DB size ratio where new files will be deleted immediately.
225    *
226    * @param ratio the trash/DB size ratio.
227    */
setMaxTrashDBRatio(final double ratio)228   public void setMaxTrashDBRatio(final double ratio) {
229     setMaxTrashDBRatio(nativeHandle_, ratio);
230   }
231 
newSstFileManager(final long handle, final long logger_handle, final long rateBytesPerSec, final double maxTrashDbRatio, final long bytesMaxDeleteChunk)232   private native static long newSstFileManager(final long handle,
233       final long logger_handle, final long rateBytesPerSec,
234       final double maxTrashDbRatio, final long bytesMaxDeleteChunk)
235       throws RocksDBException;
setMaxAllowedSpaceUsage(final long handle, final long maxAllowedSpace)236   private native void setMaxAllowedSpaceUsage(final long handle,
237       final long maxAllowedSpace);
setCompactionBufferSize(final long handle, final long compactionBufferSize)238   private native void setCompactionBufferSize(final long handle,
239       final long compactionBufferSize);
isMaxAllowedSpaceReached(final long handle)240   private native boolean isMaxAllowedSpaceReached(final long handle);
isMaxAllowedSpaceReachedIncludingCompactions( final long handle)241   private native boolean isMaxAllowedSpaceReachedIncludingCompactions(
242       final long handle);
getTotalSize(final long handle)243   private native long getTotalSize(final long handle);
getTrackedFiles(final long handle)244   private native Map<String, Long> getTrackedFiles(final long handle);
getDeleteRateBytesPerSecond(final long handle)245   private native long getDeleteRateBytesPerSecond(final long handle);
setDeleteRateBytesPerSecond(final long handle, final long deleteRate)246   private native void setDeleteRateBytesPerSecond(final long handle,
247         final long deleteRate);
getMaxTrashDBRatio(final long handle)248   private native double getMaxTrashDBRatio(final long handle);
setMaxTrashDBRatio(final long handle, final double ratio)249   private native void setMaxTrashDBRatio(final long handle, final double ratio);
disposeInternal(final long handle)250   @Override protected final native void disposeInternal(final long handle);
251 }
252