/ 
Protobuf-0.03
/ Protobuf::Arena

NAME

Protobuf::Arena - Memory arena for Protocol Buffer messages

VERSION

version 0.03

SYNOPSIS

use Protobuf::Arena;

# Create a new arena
my $arena = Protobuf::Arena->new;

# Messages can be created within a specific arena
# (This is usually handled internally when creating messages)
# my $msg = MyMessage->new(arena => $arena);

# tmpfs-backed arena for inter-process communication
my $shm_arena = Protobuf::Arena->new_tmpfs('/dev/shm/my_proto_ipc', 65536);
my $attached_arena = Protobuf::Arena->attach_tmpfs('/dev/shm/my_proto_ipc', 65536);

DESCRIPTION

This module wraps the upb_Arena type from the upb library. Arenas provide an efficient way to manage the memory lifecycle of Protocol Buffer messages and their submessages. All memory allocated for messages within an arena is freed at once when the arena itself is destroyed (typically when the Protobuf::Arena object goes out of scope).

This approach reduces the overhead of individual allocations and deallocations, significantly improving performance, especially for complex messages or high-throughput scenarios.

Key architectural features related to arenas in this implementation:

  • **Ownership:** Top-level Protobuf::Message objects usually create and own their Protobuf::Arena instance.

  • **Shared Memory (tmpfs):** Supports creating arenas backed by tmpfs for high-performance, zero-copy Inter-Process Communication (IPC), as detailed in perl/doc/architecture/advanced/01-tmpfs-ipc-design.md.

  • **Memory Canaries:** Arenas use canary bytes (0xDEADBEEFCAFEBABEULL) to detect memory corruption (buffer overflows/underflows) within arena-allocated blocks.

  • **NUMA Awareness:** (Planned) Optimizations for memory placement on multi-socket systems.

METHODS

== Class Methods

new()

my $arena = Protobuf::Arena->new;

Creates a new, standard memory-backed arena.

new_tmpfs($path, $size)

my $arena = Protobuf::Arena->new_tmpfs('/dev/shm/my_ipc', 1048576);

Creates a new arena backed by a file in tmpfs at the given $path with a specified $size. This is used for shared memory IPC.

attach_tmpfs($path, $size)

my $arena = Protobuf::Arena->attach_tmpfs('/dev/shm/my_ipc', 1048576);

Attaches to an existing tmpfs-backed arena at $path with the given $size.

== Instance Methods

space_allocated()

Returns the total bytes currently allocated by objects within the arena.

space_reserved()

Returns the total bytes reserved by the arena from the system, including any overhead or preallocated blocks.

stats()

Returns a hash reference containing detailed memory usage statistics for the arena, such as allocated bytes, reserved bytes, and block counts.

is_tmpfs()

Returns true if the arena is backed by tmpfs.

get_path()

If the arena is tmpfs-backed, returns the file system path.

verify_selinux()

(Experimental) Performs checks related to SELinux contexts if being used with tmpfs-backed arenas for secure IPC.

get_offset($pointer_iv)

Given an integer representing a memory address within the arena, returns the offset from the base of the arena's memory block. Used for shared memory IPC handle serialization.

attach_message($message_full_name, $offset)

(Experimental) Reifies a message object of the given type ($message_full_name) from the arena memory at the specified $offset. Used for shared memory IPC.

set_numa_node($node)

(Planned) Sets the preferred NUMA node for memory allocations within this arena.

DEMOLISH()

Internal method. Frees the underlying upb_Arena and all memory associated with it when the Perl object is destroyed.

Clone()

Creates a new, empty Protobuf::Arena. It does *not* copy the contents of the original arena.

SEE ALSO

Protobuf, Protobuf::Message

AUTHOR

C.J. Collier <cjac@google.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Google LLC.

This is free software; you can redistribute it and/or modify it under the terms of the BSD 3-Clause License.