Class
OutOfProcessReferenceResolver
A reference resolver that launches and interactively communicates with another process or service to resolve links.
class OutOfProcessReferenceResolver
Discussion
If your external reference resolver or an external symbol resolver is implemented in another executable, you can use this object to communicate between DocC and the docc executable.
Launching and responding to requests
When creating an out-of-process resolver using init(processLocation:errorOutputHandler:) to communicate with another executable; DocC launches your link resolver executable and declares its own OutOfProcessReferenceResolver.Capabilities as a raw value passed via the --capabilities option. Your link resolver executable is expected to respond with a OutOfProcessReferenceResolver.ResponseV2.identifierAndCapabilities(_:_:) message that declares:
After this “handshake” your link resolver executable is expected to wait for OutOfProcessReferenceResolver.RequestV2 messages from DocC and respond with exactly one OutOfProcessReferenceResolver.ResponseV2 per message. A visual representation of this flow of execution can be seen in the diagram below:
DocC link resolver executable
┌─┐ ╎
│ ├─────────── Launch ──────────▶┴┐
│ │ --capabilities │ │
│ │ │ │
│ ◀───────── Handshake ─────────┤ │
│ │ { "identifier" : ... , │ │
│ │ "capabilities" : ... } │ │
┏ loop ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ │ │ │ │ ┃
┃ │ ├────────── Request ──────────▶ │ ┃
┃ │ │ { "link" : ... } OR │ │ ┃
┃ │ │ { "symbol" : ... } │ │ ┃
┃ │ │ │ │ ┃
┃ │ ◀────────── Response ─────────┤ │ ┃
┃ │ │ { "resolved" : ... } OR │ │ ┃
┃ │ │ { "failure" : ... } │ │ ┃
┃ │ │ │ │ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
│ │ └─┘
│ │ ╎
Interacting with a Convert Service
When creating an out-of-process resolver using init(bundleID:server:convertRequestIdentifier:) to communicate with another process using a ConvertService; DocC sends that service "resolve-reference" messages with aOutOfProcessReferenceResolver.Request payload and expects a "resolved-reference-response" responses with a OutOfProcessReferenceResolver.Response payload.
Because the ConvertService messages are implicitly tied to these outdated—and no longer recommended—request and response types, the richness of its responses is limited.
Note
when interacting with a ConvertService your service also needs to handle “asset” requests (asset(_:) and responses that (asset(_:)) that link resolver executables don’t need to handle.
Topics
Messages
Requests that DocC sends to your link resolver executable and the responses that it should send back.
Finding common capabilities
Ways that your link resolver executable can signal any optional capabilities that it supports.
Deprecated messages
Structures
Initializers
Instance Properties
Instance Methods