The runtime half of protoc-gen-clojure's generated-code contract.
Generated files call exactly four things here: file-descriptor to rebuild
their embedded FileDescriptorProto, known-file for well-known-type deps,
message for a prototype per message, and field for a handle per field.
Everything protobuf decides per edition — presence, delimited encoding, utf8
validation, packedness — is resolved by protobuf-java when the descriptor is
built, which is why generated code never mentions editions at all.
field returns a precomputed FieldHandle rather than a bare FieldDescriptor:
the codec's hot path dispatches on a keyword and never touches the descriptor
API per call. Handles are built against a specific prototype, so a
message-typed field's nested prototype has the right concrete class in both
the DynamicMessage and generated-class arms.
The runtime half of protoc-gen-clojure's generated-code contract. Generated files call exactly four things here: `file-descriptor` to rebuild their embedded FileDescriptorProto, `known-file` for well-known-type deps, `message` for a prototype per message, and `field` for a handle per field. Everything protobuf decides per edition — presence, delimited encoding, utf8 validation, packedness — is resolved by protobuf-java when the descriptor is built, which is why generated code never mentions editions at all. `field` returns a precomputed FieldHandle rather than a bare FieldDescriptor: the codec's hot path dispatches on a keyword and never touches the descriptor API per call. Handles are built against a specific prototype, so a message-typed field's nested prototype has the right concrete class in both the DynamicMessage and generated-class arms.
(compiled-message fd lookup)A compiled-codec prototype, whatever the codec setting.
A compiled-codec prototype, whatever the codec setting.
(compiled-message? msg)True when msg is the compiled codec's own Message — the arm a prototype
takes when no generated Java class matches. The guard slot requires.
True when msg is the compiled codec's own Message — the arm a prototype takes when no generated Java class matches. The guard `slot` requires.
(dynamic-message fd lookup)A DynamicMessage prototype, whatever the codec setting: the reference arm, for tests and comparisons.
A DynamicMessage prototype, whatever the codec setting: the reference arm, for tests and comparisons.
(field prototype field-name)A precomputed handle for one field of a message prototype, looked up by its exact proto field name — the name is the authority; kebab-cased keys are derived from it, never the reverse (STYLE_LEGACY files can mix conventions).
A precomputed handle for one field of a message prototype, looked up by its exact proto field name — the name is the authority; kebab-cased keys are derived from it, never the reverse (STYLE_LEGACY files can mix conventions).
(file-descriptor descriptor-b64 deps)Build a FileDescriptor from the base64 FileDescriptorProto a generated file
embeds, linked against its dependencies (already-built FileDescriptors —
sibling namespaces' file-descriptor vars or known-file results).
Build a FileDescriptor from the base64 FileDescriptorProto a generated file embeds, linked against its dependencies (already-built FileDescriptors — sibling namespaces' `file-descriptor` vars or `known-file` results).
(java-class-hint d)The Java class protoc generates for this message, by the emitter's rule —
the hint a generated namespace passes to message for it — or nil when the
rule declines to guess. Only ever a hint: prototype verifies it.
The Java class protoc generates for this message, by the emitter's rule — the hint a generated namespace passes to `message` for it — or nil when the rule declines to guess. Only ever a hint: `prototype` verifies it.
(known-file path)The FileDescriptor for a well-known type bundled in protobuf-java, e.g. "google/protobuf/timestamp.proto".
The FileDescriptor for a well-known type bundled in protobuf-java, e.g. "google/protobuf/timestamp.proto".
(message fd lookup)(message fd lookup class-hint)The prototype for a message type: a default instance whose
.newBuilderForType the generated ->proto fns drive.
With a Java class hint (3-arity) the generated class's default instance is used when it is present and describes the same message — protoc's own serializer, and the fastest arm. Otherwise, and always in the 2-arity, the compiled codec's prototype: a Message over a slot array with the descriptor compiled once into reader and writer tables. DynamicMessage serves only for extendable types, which the compiled codec does not support, or when -Dclj-protobuf.codec=dynamic asks for it. Same codec, same field descriptors, same bytes on every arm.
The prototype for a message type: a default instance whose `.newBuilderForType` the generated `->proto` fns drive. With a Java class hint (3-arity) the generated class's default instance is used when it is present and describes the same message — protoc's own serializer, and the fastest arm. Otherwise, and always in the 2-arity, the compiled codec's prototype: a Message over a slot array with the descriptor compiled once into reader and writer tables. DynamicMessage serves only for extendable types, which the compiled codec does not support, or when -Dclj-protobuf.codec=dynamic asks for it. Same codec, same field descriptors, same bytes on every arm.
(prototype x)The prototype for a message type from its Descriptor, or from any Message
of that type — the same arm message hands the generated namespace: the
generated class when it is on the classpath (its name derived by the
emitter's own rule), else the compiled codec, else DynamicMessage for
extendable types or under -Dclj-protobuf.codec=dynamic.
For code that manufactures prototypes for types it did not generate —
gRPC marshallers, say — and must land on the arm the generated proto->X
fns read. A generated-class or compiled prototype passed in comes back as
it is; a DynamicMessage is re-resolved, so a consumer that built one
before 0.2.0 wraps that one call and needs no other change.
The prototype for a message type from its Descriptor, or from any Message of that type — the same arm `message` hands the generated namespace: the generated class when it is on the classpath (its name derived by the emitter's own rule), else the compiled codec, else DynamicMessage for extendable types or under -Dclj-protobuf.codec=dynamic. For code that manufactures prototypes for types it did not generate — gRPC marshallers, say — and must land on the arm the generated `proto->X` fns read. A generated-class or compiled prototype passed in comes back as it is; a DynamicMessage is re-resolved, so a consumer that built one before 0.2.0 wraps that one call and needs no other change.
(slot msg i)One slot of a compiled message, by index, in slot representation. nil is absent; for a field without presence nil also means the default.
Guard every call with compiled-message?. This does not check, because the
whole point is to cost less than a field read through the codec, and a
message from another arm throws rather than answering — the same rule
codec/get-field documents for handles.
One slot of a compiled message, by index, in slot representation. nil is absent; for a field without presence nil also means the default. Guard every call with `compiled-message?`. This does not check, because the whole point is to cost less than a field read through the codec, and a message from another arm throws rather than answering — the same rule `codec/get-field` documents for handles.
(slot-of handle)The slot index this handle reads, or nil when its prototype is not on the compiled arm. Read once at generation time, never on the hot path.
The index is the field's declaration index in its descriptor — exactly
(.getIndex fd) — so a generator that already has the descriptor may bake
the literal and never call this at all. Generated files are checked in and
long-lived, so that equivalence is contract, not an implementation detail.
The slot index this handle reads, or nil when its prototype is not on the compiled arm. Read once at generation time, never on the hot path. The index is the field's declaration index in its descriptor — exactly `(.getIndex fd)` — so a generator that already has the descriptor may bake the literal and never call this at all. Generated files are checked in and long-lived, so that equivalence is contract, not an implementation detail.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |