net.openhft.chronicle.queue.RollCycle Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of chronicle-queue Show documentation
Java library for persisted low latency messaging (Java 8+)
There is a newer version: 5.27ea0
/*
 * Copyright 2016-2020 chronicle.software
 *
 *       https://chronicle.software
 *
 * 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 net.openhft.chronicle.queue;

import net.openhft.chronicle.core.time.TimeProvider;
import org.jetbrains.annotations.NotNull;

public interface RollCycle {

    /**
     * Returns the format that is to be applied when file names are calculated for a new roll cycle.
     * 
     * For example, the following formats can be returned:
     * 

     *     "yyyyMMdd-HHmm" (MINUTELY)
     *     "yyyyMMdd" (DAILY)
     * 
     * Lexicographical order of formatted cycles must preserve chronological order, i.e. if {@code cycle1 < cycle2},
     * the same relation must be kept for their string representations.
     *
     * @return the format that is to be applied when file names are calculated for a new roll cycle
     */
    @NotNull
    String format();

    /**
     * Returns the length in milliseconds (i.e. the maximum duration) for a roll cycle.
     * 
     * For example, the following lengths can be returned:
     * 

     *     60 * 1,000 = 60,000 (MINUTELY)
     *     24 * 60 * 60 * 1,000 = 86,400,000 (DAILY)
     * 
     *
     * @return the length in milliseconds (i.e. the maximum duration) for a roll cycle
     */
    int lengthInMillis();

    /**
     * @return the default epoch offset if one is not set
     */
    default int defaultEpoch() {
        return 0;
    }

    /**
     * @return the size of each index array, note: indexCount^2 is the maximum number of index queue entries.
     */
    int defaultIndexCount();

    /**
     * Returns the space between excerpts that are explicitly indexed.
     * 
     * A higher number means higher sequential write performance but slower random access read. The sequential read performance is not affected by
     * this property.
     * 

     * For example, the following default index spacing can be returned:
     * 

     *     16 (MINUTELY)
     *     64 (DAILY)
     * 
     *
     * @return the space between excerpts that are explicitly indexed
     */
    int defaultIndexSpacing();

    /**
     * Returns the current cycle. Default epoch is 0 so for a DAILY cycle this will return the number of days since 1970-01-01T00:00:00Z.
     *
     * @param epoch an EPOCH offset, to all the user to define their own epoch
     * @return the current cycle
     */
    default int current(@NotNull TimeProvider time, long epoch) {
        return (int) ((time.currentTimeMillis() - epoch) / lengthInMillis());
    }

    /**
     * Returns the index for the provided {@code cycle} and {@code sequenceNumber}.
     * 
     * An index is made up of {@code cycle} shifted left + {@code sequenceNumber}. {@code sequenceNumber} starts at 0 for each new {@code cycle}.
     * DAILY cycle has cycleShift=32 and sequenceMask=0xFFFFFFFF so the top 32 bits are for cycle and bottom
     * 32 bits are for sequence. This means you can only store 2^32 entries per day.
     * HUGE_DAILY has shift=48 and mask=0xFFFFFFFFFFFF thus allowing 2^48 entries per day.
     *
     * @param cycle          to be composed into an index
     * @param sequenceNumber to be composed into an index
     * @return the index for the given {@code cycle} and {@code sequenceNumber}
     */
    long toIndex(int cycle, long sequenceNumber);

    /**
     * Returns the sequence number for the provided {@code index}.
     * 

     * An index comprises both a cycle and a sequence number but the way the index is composed of said properties may vary. This method
     * decomposes the provided {@code index} and extracts the sequence number.
     *
     * @param index to use to extract the sequence number
     * @return the sequence number for the provided {@code index}
     */
    long toSequenceNumber(long index);

    /**
     * Returns the cycle for the given {@code index}.
     * 
     * An index comprises both a cycle and a sequence number but the way the index is composed of said properties may vary. This method
     * decomposes the provided {@code index} and extracts the cycle.
     *
     * @param index to use when extracting the cycle
     * @return the sequence number for the given {@code index}
     */
    int toCycle(long index);

    /**
     * @return the maximum number of messages per cycle
     */
    long maxMessagesPerCycle();

    // sanity checking of index maximums and counts
    int MAX_INDEX_COUNT = 32 << 10;
}