pub trait ProvidesBoundGlobal<I: Proxy, const API_COMPAT_VERSION: u32> {
// Required method
fn bound_global(&self) -> Result<I, GlobalError>;
// Provided method
fn with_min_version(&self, version: u32) -> Result<I, GlobalError> { ... }
}
Expand description
A trait implemented by types that provide access to capability globals.
The returned global must be fully compatible with the provided API_COMPAT_VERSION
generic
argument. For example:
- A global that binds to
wl_compositor
with maximum version 4 could implementProvidesBoundGlobal<WlCompositor, 4>
,ProvidesBoundGlobal<WlCompositor, 3>
,ProvidesBoundGlobal<WlCompositor, 2>
, andProvidesBoundGlobal<WlCompositor, 1>
because versions 2-4 only add additional requests to thewl_surface
API. - A global that binds to
wl_compositor
with maximum version 5 may only implementProvidesBoundGlobal<WlCompositor, 5>
because version 5 makes usingwl_surface::attach
with a nonzero offset a protocol error. A caller who is only aware of the version 4 API risks causing these protocol errors if it uses surfaces created by such a global.
Changes that cause compatibility breaks include:
- Adding a new event to the global or to any object created by the global.
- Adding a new requirement to an existing request.
The resulting global may have a version lower than API_COMPAT_VERSION
if, at runtime, the
compositor does not support the new version. Clients should either be prepared to handle
earlier versions of the protocol or use ProvidesBoundGlobal::with_min_version
to produce an
error in this case.
It is permitted to implement ProvidesBoundGlobal
for versions that are higher than the
maximum version you bind. When rustc gains the ability to constrain const parameters with
integer bounds (where API_COMPAT_VERSION >= 5
), implementations of this trait should be
provided by specifying a lower bound for the compat version in order to avoid requiring version
updates be done in lock-step.