Implementation:Apache Paimon MemorySize

Knowledge Sources	Apache_Paimon
Domains	Memory Configuration, Type Safety, Human-Readable Units
Last Updated	2026-02-08 00:00 GMT

Overview

MemorySize represents a memory size in bytes with human-readable parsing and formatting, supporting units from bytes to terabytes.

Description

MemorySize (public API since 0.4.0) wraps a long byte count and provides static factory methods (ofMebiBytes(), ofKibiBytes(), ofBytes()) and unit-based getters (getBytes(), getKibiBytes(), getMebiBytes(), getGibiBytes(), getTebiBytes()). The class includes a parse(String) method that interprets text expressions like "128mb", "1gb", "256 kb" where pure numbers are treated as bytes.

Formatting is available via toString() and toHumanReadableString() with memoized results for performance. The class supports comparison via Comparable<MemorySize> and arithmetic operations including add(), subtract(), multiply(), and divide(). It defines an inner MemoryUnit enum with BYTES, KILO_BYTES, MEGA_BYTES, GIGA_BYTES, TERA_BYTES and their conversion multipliers (powers of 1024).

Pre-defined constants include ZERO, MAX_VALUE, VALUE_32_KB, VALUE_8_MB, VALUE_128_MB, and VALUE_256_MB. This class is used throughout Paimon's configuration system for memory-related options such as target file size, write buffer size, and cache sizes, providing type-safe memory configuration with flexible parsing and preventing errors from raw numeric values.

Usage

Use MemorySize to configure memory-related table options with human-readable values and to perform type-safe memory calculations.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/options/MemorySize.java
• Lines: 1-440

Signature

@Public
public class MemorySize implements java.io.Serializable, Comparable<MemorySize> {

    public static final MemorySize ZERO = new MemorySize(0L);
    public static final MemorySize MAX_VALUE = new MemorySize(Long.MAX_VALUE);
    public static final MemorySize VALUE_32_KB = MemorySize.ofKibiBytes(32);
    public static final MemorySize VALUE_128_MB = MemorySize.ofMebiBytes(128);
    public static final MemorySize VALUE_256_MB = MemorySize.ofMebiBytes(256);

    private final long bytes;

    // Constructors and factory methods
    public MemorySize(long bytes) { }
    public static MemorySize ofMebiBytes(long mebiBytes) { }
    public static MemorySize ofKibiBytes(long kibiBytes) { }
    public static MemorySize ofBytes(long bytes) { }

    // Getters
    public long getBytes() { return bytes; }
    public long getKibiBytes() { return bytes >> 10; }
    public int getMebiBytes() { return (int) (bytes >> 20); }
    public long getGibiBytes() { return bytes >> 30; }
    public long getTebiBytes() { return bytes >> 40; }

    // Parsing
    public static MemorySize parse(String text);
    public static MemorySize parse(String text, MemoryUnit defaultUnit);

    // Arithmetic
    public MemorySize add(MemorySize that);
    public MemorySize subtract(MemorySize that);
    public MemorySize multiply(double multiplier);
    public MemorySize divide(long by);

    // Formatting
    public String toString();
    public String toHumanReadableString();

    @Override
    public int compareTo(MemorySize that) {
        return Long.compare(this.bytes, that.bytes);
    }

    // Inner enum
    public enum MemoryUnit {
        BYTES, KILO_BYTES, MEGA_BYTES, GIGA_BYTES, TERA_BYTES
    }
}

Import

import org.apache.paimon.options.MemorySize;

I/O Contract

Inputs

Name	Type	Required	Description
bytes	long	yes	Number of bytes (must be >= 0)
text	String	yes (for parse)	Memory size string (e.g., "128mb", "1gb")
defaultUnit	MemoryUnit	no	Default unit when parsing number without unit

Outputs

Name	Type	Description
bytes	long	Memory size in bytes
kibiBytes	long	Memory size in kibibytes (1024 bytes)
mebiBytes	int	Memory size in mebibytes (1024 kibibytes)
gibiBytes	long	Memory size in gibibytes (1024 mebibytes)
tebiBytes	long	Memory size in tebibytes (1024 gibibytes)

Usage Examples

Creating and Parsing Memory Sizes

import org.apache.paimon.options.MemorySize;

// Create using factory methods
MemorySize size1 = MemorySize.ofMebiBytes(128);
MemorySize size2 = MemorySize.ofKibiBytes(32);
MemorySize size3 = MemorySize.ofBytes(1024);

System.out.println("128 MB: " + size1.getBytes() + " bytes");
System.out.println("32 KB: " + size2.getBytes() + " bytes");

// Parse from strings
MemorySize parsed1 = MemorySize.parse("256mb");
MemorySize parsed2 = MemorySize.parse("1gb");
MemorySize parsed3 = MemorySize.parse("512 kb");
MemorySize parsed4 = MemorySize.parse("1048576");  // bytes

System.out.println("256mb = " + parsed1.getMebiBytes() + " MB");
System.out.println("1gb = " + parsed2.getGibiBytes() + " GB");

// Parse with default unit
MemorySize withDefault = MemorySize.parse("100", MemorySize.MemoryUnit.MEGA_BYTES);
System.out.println("100 (default MB) = " + withDefault.getMebiBytes() + " MB");

Arithmetic Operations

import org.apache.paimon.options.MemorySize;

MemorySize size1 = MemorySize.ofMebiBytes(128);
MemorySize size2 = MemorySize.ofMebiBytes(64);

// Addition
MemorySize sum = size1.add(size2);
System.out.println("128 MB + 64 MB = " + sum.getMebiBytes() + " MB");

// Subtraction
MemorySize diff = size1.subtract(size2);
System.out.println("128 MB - 64 MB = " + diff.getMebiBytes() + " MB");

// Multiplication
MemorySize doubled = size1.multiply(2.0);
System.out.println("128 MB * 2 = " + doubled.getMebiBytes() + " MB");

// Division
MemorySize half = size1.divide(2);
System.out.println("128 MB / 2 = " + half.getMebiBytes() + " MB");

Comparison and Formatting

import org.apache.paimon.options.MemorySize;

MemorySize size1 = MemorySize.ofMebiBytes(256);
MemorySize size2 = MemorySize.ofKibiBytes(128);

// Comparison
if (size1.compareTo(size2) > 0) {
    System.out.println("256 MB is larger than 128 KB");
}

// Formatting
System.out.println("toString: " + size1.toString());
System.out.println("Human readable: " + size1.toHumanReadableString());

// Using constants
MemorySize defaultSize = MemorySize.VALUE_128_MB;
MemorySize minSize = MemorySize.VALUE_32_KB;

System.out.println("Default: " + defaultSize);
System.out.println("Minimum: " + minSize);

Configuration Usage

import org.apache.paimon.options.MemorySize;
import org.apache.paimon.options.Options;
import org.apache.paimon.CoreOptions;

// Set memory size in options
Options options = new Options();
options.set("target-file-size", "128mb");
options.set("write-buffer-size", "256mb");

// Parse from options
MemorySize targetFileSize = MemorySize.parse(options.get("target-file-size"));
MemorySize bufferSize = MemorySize.parse(options.get("write-buffer-size"));

System.out.println("Target file size: " + targetFileSize.toHumanReadableString());
System.out.println("Buffer size: " + bufferSize.toHumanReadableString());

// Using CoreOptions
CoreOptions coreOptions = new CoreOptions(options);
MemorySize actualSize = coreOptions.targetFileSize();
System.out.println("Actual target size: " + actualSize.getMebiBytes() + " MB");

Related Pages

• Principle:Apache_Paimon_Table_Configuration