/ 
Protobuf-0.04
/ Protobuf::Message

NAME

Protobuf::Message - Base class for Protocol Buffer messages

VERSION

version 0.04

SYNOPSIS

# This class is not used directly. Instead, use classes generated
# from your .proto files.

# Example assuming MyPackage::MyMessage is generated:
# use MyPackage::MyMessage;

# my $msg = MyPackage::MyMessage->new(field1 => 'value1');
# $msg->field2(123);

# my $binary = $msg->serialize;
# my $decoded = MyPackage::MyMessage->parse($binary);

# is($decoded->field1, 'value1', 'Field 1 matches');

DESCRIPTION

Protobuf::Message is the base class for all Perl classes generated from Protocol Buffer message definitions. It provides the core functionality for creating, manipulating, serializing, and deserializing messages.

You should not use this class directly. Instead, compile your .proto files using protoc with the protoc-gen-perl-pb plugin, which will generate subclasses of Protobuf::Message with methods specific to your message fields.

The underlying implementation uses the upb library, and most method calls are dispatched to highly optimized C functions via XS.

ATTRIBUTES

Message classes generated by the plugin will have attributes corresponding to the fields defined in the .proto file. These are not defined directly in this base class but are injected by Protobuf::ClassGenerator based on the message descriptor.

METHODS

== Class Methods

new(%args)

my $msg = MyGeneratedMessage->new(
    field_a => 'hello',
    nested_msg => { inner_field => 123 },
    repeated_field => [1, 2, 3],
);

Creates a new message instance. Fields can be initialized using key-value pairs.

This method cannot be called on Protobuf::Message directly; it must be called on a generated subclass.

parse($binary_data)

my $msg = MyGeneratedMessage->parse($binary_string);

Parses a binary string (wire format) and returns a new message instance.

parse_from($binary_data)

$msg->parse_from($binary_string);

Parses a binary string and merges its fields into the existing message instance.

merge_from($other_msg)

$msg->merge_from($other_msg);

Deep-merges the fields from $other_msg into the current message. $other_msg must be of the same type.

copy_from($other_msg)

$msg->copy_from($other_msg);

Deep-copies the fields from $other_msg into the current message, clearing any existing fields first.

from_json($json_string)

my $msg = MyGeneratedMessage->from_json($json_string);

Parses a JSON string representing the message and returns a new message instance.

descriptor()

my $mdef = MyGeneratedMessage->descriptor;
print $mdef->full_name;

Returns the Protobuf::Descriptor::MessageDef object for this message type.

== Instance Methods

Most field-specific methods (getters, setters, etc.) are dynamically generated in subclasses. The methods listed below are common to all messages.

get($field_name)

Generic accessor to get a field's value. Prefer using the field-specific methods in generated classes (e.g., $msg->my_field).

set($field_name, $value)

Generic accessor to set a field's value. Prefer using the field-specific methods in generated classes (e.g., $msg->my_field('new_value')).

has_field($field_name)

Returns true if the specified singular field is set. Prefer $msg->has_my_field.

clear_field($field_name)

Clears the specified field. Prefer $msg->clear_my_field.

serialize()

my $binary_string = $msg->serialize;

Serializes the message to the binary wire format.

to_text()

my $text_format = $msg->to_text;

Converts the message to the Protocol Buffer TextFormat. Useful for debugging.

to_json()

my $json_string = $msg->to_json;

Converts the message to its JSON representation.

unknown_fields()

Returns a Protobuf::UnknownFieldSet object representing any fields encountered during parsing that were not defined in the message's descriptor.

fields()

my @fields = $msg->fields;

Returns a list of Protobuf::Descriptor::Field objects for all fields that are currently set in the message.

CLONE()

Throws an error. Protobuf messages cannot be directly cloned, especially across threads, due to the underlying C structures and arena management.

DESTROY()

Internal method to clean up the underlying upb_Message and related resources.

ADVANCED METHODS

These methods are for more specialized use cases.

set_oneof($oneof_name, $value)

Sets a value within a oneof group. This method attempts to coerce the given $value into the first field within the named oneof group that can accept it. Returns the name of the field that was set.

which_oneof($oneof_name)

Returns the name of the field that is currently set within the specified oneof group, or undef if no field is set.

audit_integrity()

Internal method for debugging memory and object cache integrity.

get_fingerprint()

Returns a unique fingerprint string for the message instance, often related to its memory location in the arena. Useful for debugging and tracking object identity in shared memory scenarios.

freeze_to_shared($path, $size)

(Experimental) Serializes and copies the message into a shared memory segment (tmpfs) at the given $path, with a maximum $size. Returns a new instance backed by the shared arena.

thaw_from_shared($class, $path, $size)

(Experimental) Attaches to an existing shared memory segment at $path and attempts to reify a message of type $class from it.

to_perl()

Converts the message to a Perl hash/array structure. Protobuf::WKT::Struct has a specialized version.

from_perl($hashref)

Populates the message fields from a Perl hashref.

validate()

(Placeholder) Validates the message content based on any defined constraints.

coerce_to($target_class)

(Placeholder) Attempts to coerce the current message to an instance of $target_class.

to_text_with_unknowns()

(Placeholder) Converts the message to TextFormat, including a representation of any unknown fields. Currently alias to to_text().

to_wire()

Alias for serialize(). Returns the binary wire format.

to_json_streaming()

(Placeholder) Returns a JSON representation of the message, potentially optimized for streaming. Currently alias to to_json().

to_json_compact()

Returns a JSON representation of the message without extra whitespace.

dependency_graph()

(Placeholder) Returns a structure representing the dependencies of this message type.

perf_profile()

(Placeholder) Returns a hash containing performance metrics related to this message.

reset_connection()

(Placeholder) Resets any connection-related state within the message object.

MEMORY MANAGEMENT

Protobuf::Message instances are typically allocated on a Protobuf::Arena. The arena manages the memory for the message and all its submessages. When the arena is freed (usually when the top-level message object goes out of scope), all associated memory is reclaimed.

SEE ALSO

Protobuf, Protobuf::DescriptorPool, Protobuf::Arena, Protobuf::Descriptor

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.