Transactional registration for external codec packages.
A package application can publish its complete codec set and table-provider set with one ownership token:
{:ok, token} =
Iconvex.Extension.register(
[
MyPackage.Codec,
{MyPackage.OtherCodec,
canonical: "MY-SOURCE-OTHER", aliases: ["MY-OTHER"]}
],
owner: :my_package,
priority: 0,
table_providers: [:my_table]
)
# Store `token` in the application state.
:ok = Iconvex.Extension.unregister(token)An atom in :table_providers uses the package :owner as its OTP
application. {table_id, application} may be used when the table files live
in a different application.
Providers become available before the codec routes are committed. Registration failure rolls back every provider acquired by this transaction. Shutdown removes codec routes before providers, so a concurrent conversion cannot resolve a new codec against a missing provider. The route snapshot makes each commit or removal externally atomic.
The token is opaque and exact. Passing an unknown or stale token is an idempotent no-op, and provider cleanup uses the underlying ownership references so it cannot remove a later replacement. Repeating an identical registration for the same owner adopts the committed token, including after a supervised registry-worker restart. A different active transaction for that owner is rejected.
Managed name claims are deterministic: canonical claims outrank aliases, then the larger integer priority wins within the same claim kind. Equal-rank claims by different modules are rejected as ambiguous. Priorities should be fixed package metadata, not runtime configuration.
Summary
Types
A module or a module with registration-specific canonical name and aliases.
Registration options.
A table ID using the owner application, or an explicit table ID/application pair.
Opaque ownership token for one complete package transaction.
Functions
Atomically registers one external package's codecs and table providers.
Removes the transaction owned by token.
Types
A module or a module with registration-specific canonical name and aliases.
@type register_option() :: {:owner, atom()} | {:priority, integer()} | {:table_providers, [table_provider()]}
Registration options.
:owner and :priority are required. :table_providers defaults to an empty
list, allowing codec-only packages. An empty codec and provider set is
rejected; provider-only data packages are supported.
A table ID using the owner application, or an explicit table ID/application pair.
@opaque token()
Opaque ownership token for one complete package transaction.
Functions
@spec register([codec_registration()], [register_option()]) :: {:ok, token()} | {:error, term()}
Atomically registers one external package's codecs and table providers.
Returns the same token when the active transaction for :owner has exactly
the same codec metadata, providers, and priority.
Removes the transaction owned by token.
Removal is conditional, replacement-safe, and idempotent. Unknown or already
consumed reference tokens return :ok.