<commit_before>/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.addthis.basis.collect.dbq;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import java.io.Closeable;
import java.io.IOException;

import java.util.concurrent.TimeUnit;

import java.nio.file.Path;
import java.time.Duration;

import com.google.common.base.Preconditions;

/**
 * Thread-safe FIFO queue that writes overflow elements to disk. If memory capacity is not exceeded
 * then all operations occur in memory. {@link #put( Object , byte[])}
 * requests are designed to return quickly and write to disk
 * asynchronously if one or more background threads have been configured.
 * All requests of the {@link DiskBackedQueueInternals#get(long, TimeUnit)}
 * family perform synchronous reads from the disk. A {@link #close()}
 * will write the contents of the queue to the external storage.
 *
 * <p>This implements a disk-backed queue however it is possible to set a maximum
 * capacity on disk using the {@link Builder#setDiskMaxBytes(long)} parameter.
 * If the maximum disk capacity is exceeded then insertion operations will either
 * block or throw an exception depending on whether the blocking or non-blocking
 * operation is invoked. The disk capacity restriction can be removed by setting the
 * disk max bytes to 0.
 *
 * <p>The class exposes the API of the data structure and the Builder class to construct
 * instances. Nearly all parameter are required to the Builder object.
 * This is a deliberate design decision to discourage a reliance of magical
 * default values that lead to behavior surprises for your application.
 * Refer to {@link DiskBackedQueueInternals} for the
 * the implementation.
 */
public class DiskBackedQueue<E> implements Closeable {

    private final DiskBackedQueueInternals<E> queue;

    private DiskBackedQueue(DiskBackedQueueInternals<E> queue) {
        this.queue = queue;
    }

    public static class Builder<E> {
        private int pageSize = -1;
        private int memMinCapacity = -1;
        private int memMaxCapacity = -1;
        private long diskMaxBytes = -1;
        private int numBackgroundThreads = -1;
        private int compressionLevel = 9;
        private int compressionBuffer = 1024;
        private boolean memoryDouble = false;
        private Path path;
        private Serializer<E> serializer;
        private Duration terminationWait;
        private Boolean shutdownHook;
        private Boolean compress;

        // optional
        private boolean silent;

        /**
         * Number of elements that are stored per page. Larger
         * pages amortize the cost of writing to disk but very large
         * pages limit the concurrency of background writes. Suggested
         * values are in the range from 32 to 4096. This parameter is required.
         */
        public Builder setPageSize(int size) {
            this.pageSize = size;
            return this;
        }

        /**
         * Minimum number of elements that are allowed to be stored
         * in memory. An implementation note: half of these elements
         * will be reserved for the reading queue, and half will be
         * reserved fo the write queue. Suggested values are a 10x to 100x
         * multiple of the page size. The value muse be greater than
         * or equal to page size. This parameter is required.
         */
        public Builder setMemMinCapacity(int capacity) {
            this.memMinCapacity = capacity;
            return this;
        }

        /**
         * Maximum number of elements that are allowed to be stored
         * in memory before insertion operations begin writing
         * synchronously to write to disk. The value muse be greater than
         * or equal to memory minimum capacity. This parameter is required.
         */
        public Builder setMemMaxCapacity(int capacity) {
            this.memMaxCapacity = capacity;
            return this;
        }

        /**
         * Maximum number of bytes that are allowed to be stored
         * on disk. Set to 0 to specify no upper bound. This parameter is required.
         */
        public Builder setDiskMaxBytes(long bytes) {
            this.diskMaxBytes = bytes;
            return this;
        }

        /**
         * Number of background threads for asynchronous writes to disk.
         * If 0 then all writes are synchronous. This parameter is required.
         */
        public Builder setNumBackgroundThreads(int threads) {
            this.numBackgroundThreads = threads;
            return this;
        }

        /**
         * Path to the directory for storing external pages. This parameter is required.
         */
        public Builder setPath(Path path) {
            this.path = path;
            return this;
        }

        /**
         * Serializer for reading/writing elements to/from disk.
         * This parameter is required.
         */
        public Builder setSerializer(Serializer<E> serializer) {
            this.serializer = serializer;
            return this;
        }

        /**
         * Time interval to wait for any outstanding writes to be
         * flushed to disk when queue is closed. This parameter is required.
         */
        public Builder setTerminationWait(Duration wait) {
            this.terminationWait = wait;
            return this;
        }

        /**
         * Whether or not to create a shutdown hook that will
         * close the disk backed queue on JVM shutdown.
         * This parameter is required.
         */
        public Builder setShutdownHook(boolean hook) {
            this.shutdownHook = hook;
            return this;
        }

        /**
         * If true then enable gzip compression of the external storage.
         * This parameter is required.
         */
        public Builder setCompress(boolean compress) {
            this.compress = compress;
            return this;
        }

        /**
         * If true then store the serialized representation of objects
         * along with the objects themselves. This improves
         * disk-writing performance at the cost of additional memory overhead.
         * This parameter is required. Memory doubling is ignored
         * when {@link #put(Object, byte[])} is called with a null byte array.
         * This parameter is optional. Default is false.
         */
        public Builder setMemoryDouble(boolean enable) {
            this.memoryDouble = enable;
            return this;
        }

        /**
         * If compression is enabled then this parameter sets the gzip
         * compression level. This parameter is optional. Default is 9.
         */
        public Builder setCompressionLevel(int compressionLevel) {
            this.compressionLevel = compressionLevel;
            return this;
        }

        /**
         * If compression is enabled then this parameter sets the gzip
         * compression buffer size in bytes. This parameter is optional. Default is 1024.
         */
        public Builder setCompressionBuffer(int compressionBuffer) {
            this.compressionBuffer = compressionBuffer;
            return this;
        }

        /**
         * If true then do not print informational log messages.
         * Convenience method the same functionality can be
         * configured from the logger. This parameter is optional.
         */
        public Builder setSilent(boolean silence) {
            this.silent = silence;
            return this;
        }

        public DiskBackedQueue<E> build() throws IOException {
            Preconditions.checkArgument(pageSize > 0, "pageSize must be > 0");
            Preconditions.checkArgument(memMinCapacity > 0, "memMinCapacity must be > 0");
            Preconditions.checkArgument(memMaxCapacity > 0, "memMaxCapacity must be > 0");
            Preconditions.checkArgument(diskMaxBytes >= 0, "diskMaxBytes must be >= 0");
            Preconditions.checkArgument(numBackgroundThreads >= 0, "numBackgroundThreads must be >= 0");
            Preconditions.checkNotNull(path, "path must be non-null");
            Preconditions.checkNotNull(serializer, "serializer must be non-null");
            Preconditions.checkArgument(memMaxCapacity >= pageSize, "memMaxCapacity must be >= pageSize");
            Preconditions.checkArgument(memMinCapacity <= memMaxCapacity, "memMinCapacity must be <= memMaxCapacity");
            Preconditions.checkNotNull(terminationWait, "terminationWait must be specified");
            Preconditions.checkNotNull(shutdownHook, "shutdownHook usage must be specified");
            Preconditions.checkNotNull(compress, "compress usage must be specified");
            Preconditions.checkArgument(compressionLevel >= 0 && compressionLevel <= 9, "compression level must be between 0 and 9");
            Preconditions.checkArgument(compressionBuffer > 0, "compression buffer must greater than 0");
            return new DiskBackedQueue<>(
                    new DiskBackedQueueInternals<>(pageSize, memMinCapacity / pageSize,
                                                   memMaxCapacity / pageSize,
                                                   diskMaxBytes,
                                                   numBackgroundThreads, path, serializer,
                                                   terminationWait, shutdownHook, silent, compress,
                                                   compressionLevel, compressionBuffer, memoryDouble));
        }
    }
<commit_msg>Prevent 'unchecked' warnings in DiskBackedQueue by making Builder methods preserve type<commit_after>/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.addthis.basis.collect.dbq;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import java.io.Closeable;
import java.io.IOException;

import java.util.concurrent.TimeUnit;

import java.nio.file.Path;
import java.time.Duration;

import com.google.common.base.Preconditions;

/**
 * Thread-safe FIFO queue that writes overflow elements to disk. If memory capacity is not exceeded
 * then all operations occur in memory. {@link #put( Object , byte[])}
 * requests are designed to return quickly and write to disk
 * asynchronously if one or more background threads have been configured.
 * All requests of the {@link DiskBackedQueueInternals#get(long, TimeUnit)}
 * family perform synchronous reads from the disk. A {@link #close()}
 * will write the contents of the queue to the external storage.
 *
 * <p>This implements a disk-backed queue however it is possible to set a maximum
 * capacity on disk using the {@link Builder#setDiskMaxBytes(long)} parameter.
 * If the maximum disk capacity is exceeded then insertion operations will either
 * block or throw an exception depending on whether the blocking or non-blocking
 * operation is invoked. The disk capacity restriction can be removed by setting the
 * disk max bytes to 0.
 *
 * <p>The class exposes the API of the data structure and the Builder class to construct
 * instances. Nearly all parameter are required to the Builder object.
 * This is a deliberate design decision to discourage a reliance of magical
 * default values that lead to behavior surprises for your application.
 * Refer to {@link DiskBackedQueueInternals} for the
 * the implementation.
 */
public class DiskBackedQueue<E> implements Closeable {

    private final DiskBackedQueueInternals<E> queue;

    private DiskBackedQueue(DiskBackedQueueInternals<E> queue) {
        this.queue = queue;
    }

    public static class Builder<E> {
        private int pageSize = -1;
        private int memMinCapacity = -1;
        private int memMaxCapacity = -1;
        private long diskMaxBytes = -1;
        private int numBackgroundThreads = -1;
        private int compressionLevel = 9;
        private int compressionBuffer = 1024;
        private boolean memoryDouble = false;
        private Path path;
        private Serializer<E> serializer;
        private Duration terminationWait;
        private Boolean shutdownHook;
        private Boolean compress;

        // optional
        private boolean silent;

        /**
         * Number of elements that are stored per page. Larger
         * pages amortize the cost of writing to disk but very large
         * pages limit the concurrency of background writes. Suggested
         * values are in the range from 32 to 4096. This parameter is required.
         */
        public Builder<E> setPageSize(int size) {
            this.pageSize = size;
            return this;
        }

        /**
         * Minimum number of elements that are allowed to be stored
         * in memory. An implementation note: half of these elements
         * will be reserved for the reading queue, and half will be
         * reserved fo the write queue. Suggested values are a 10x to 100x
         * multiple of the page size. The value muse be greater than
         * or equal to page size. This parameter is required.
         */
        public Builder<E> setMemMinCapacity(int capacity) {
            this.memMinCapacity = capacity;
            return this;
        }

        /**
         * Maximum number of elements that are allowed to be stored
         * in memory before insertion operations begin writing
         * synchronously to write to disk. The value muse be greater than
         * or equal to memory minimum capacity. This parameter is required.
         */
        public Builder<E> setMemMaxCapacity(int capacity) {
            this.memMaxCapacity = capacity;
            return this;
        }

        /**
         * Maximum number of bytes that are allowed to be stored
         * on disk. Set to 0 to specify no upper bound. This parameter is required.
         */
        public Builder<E> setDiskMaxBytes(long bytes) {
            this.diskMaxBytes = bytes;
            return this;
        }

        /**
         * Number of background threads for asynchronous writes to disk.
         * If 0 then all writes are synchronous. This parameter is required.
         */
        public Builder<E> setNumBackgroundThreads(int threads) {
            this.numBackgroundThreads = threads;
            return this;
        }

        /**
         * Path to the directory for storing external pages. This parameter is required.
         */
        public Builder<E> setPath(Path path) {
            this.path = path;
            return this;
        }

        /**
         * Serializer for reading/writing elements to/from disk.
         * This parameter is required.
         */
        public Builder setSerializer(Serializer<E> serializer) {
            this.serializer = serializer;
            return this;
        }

        /**
         * Time interval to wait for any outstanding writes to be
         * flushed to disk when queue is closed. This parameter is required.
         */
        public Builder<E> setTerminationWait(Duration wait) {
            this.terminationWait = wait;
            return this;
        }

        /**
         * Whether or not to create a shutdown hook that will
         * close the disk backed queue on JVM shutdown.
         * This parameter is required.
         */
        public Builder<E> setShutdownHook(boolean hook) {
            this.shutdownHook = hook;
            return this;
        }

        /**
         * If true then enable gzip compression of the external storage.
         * This parameter is required.
         */
        public Builder<E> setCompress(boolean compress) {
            this.compress = compress;
            return this;
        }

        /**
         * If true then store the serialized representation of objects
         * along with the objects themselves. This improves
         * disk-writing performance at the cost of additional memory overhead.
         * This parameter is required. Memory doubling is ignored
         * when {@link #put(Object, byte[])} is called with a null byte array.
         * This parameter is optional. Default is false.
         */
        public Builder<E> setMemoryDouble(boolean enable) {
            this.memoryDouble = enable;
            return this;
        }

        /**
         * If compression is enabled then this parameter sets the gzip
         * compression level. This parameter is optional. Default is 9.
         */
        public Builder<E> setCompressionLevel(int compressionLevel) {
            this.compressionLevel = compressionLevel;
            return this;
        }

        /**
         * If compression is enabled then this parameter sets the gzip
         * compression buffer size in bytes. This parameter is optional. Default is 1024.
         */
        public Builder<E> setCompressionBuffer(int compressionBuffer) {
            this.compressionBuffer = compressionBuffer;
            return this;
        }

        /**
         * If true then do not print informational log messages.
         * Convenience method the same functionality can be
         * configured from the logger. This parameter is optional.
         */
        public Builder<E> setSilent(boolean silence) {
            this.silent = silence;
            return this;
        }

        public DiskBackedQueue<E> build() throws IOException {
            Preconditions.checkArgument(pageSize > 0, "pageSize must be > 0");
            Preconditions.checkArgument(memMinCapacity > 0, "memMinCapacity must be > 0");
            Preconditions.checkArgument(memMaxCapacity > 0, "memMaxCapacity must be > 0");
            Preconditions.checkArgument(diskMaxBytes >= 0, "diskMaxBytes must be >= 0");
            Preconditions.checkArgument(numBackgroundThreads >= 0, "numBackgroundThreads must be >= 0");
            Preconditions.checkNotNull(path, "path must be non-null");
            Preconditions.checkNotNull(serializer, "serializer must be non-null");
            Preconditions.checkArgument(memMaxCapacity >= pageSize, "memMaxCapacity must be >= pageSize");
            Preconditions.checkArgument(memMinCapacity <= memMaxCapacity, "memMinCapacity must be <= memMaxCapacity");
            Preconditions.checkNotNull(terminationWait, "terminationWait must be specified");
            Preconditions.checkNotNull(shutdownHook, "shutdownHook usage must be specified");
            Preconditions.checkNotNull(compress, "compress usage must be specified");
            Preconditions.checkArgument(compressionLevel >= 0 && compressionLevel <= 9, "compression level must be between 0 and 9");
            Preconditions.checkArgument(compressionBuffer > 0, "compression buffer must greater than 0");
            return new DiskBackedQueue<>(
                    new DiskBackedQueueInternals<>(pageSize, memMinCapacity / pageSize,
                                                   memMaxCapacity / pageSize,
                                                   diskMaxBytes,
                                                   numBackgroundThreads, path, serializer,
                                                   terminationWait, shutdownHook, silent, compress,
                                                   compressionLevel, compressionBuffer, memoryDouble));
        }
    }

{'fraction_non_alphanumeric': 0.064818931870955, 'fraction_numerical': 0.004841658020848772, 'mean_word_length': 2.19627348807832, 'pattern_counts': {'":': 0, '<': 44, '<?xml version=': 0, '>': 66, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 20, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3750158', 'n_tokens_mistral': 4748, 'n_tokens_neox': 4538, 'n_words': 1936}