There have been a lot of questions asked lately about versioning of interfaces and protocol objects. This addition to the documentation should clear up some of those questions.
Signed-off-by: Jason Ekstrand <[email protected]> --- doc/publican/sources/Protocol.xml | 61 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml index 0ece579..f652592 100644 --- a/doc/publican/sources/Protocol.xml +++ b/doc/publican/sources/Protocol.xml @@ -164,6 +164,67 @@ </para> </section> <xi:include href="ProtocolInterfaces.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <section id="sect-Protocol-Versioning"> + <title>Versioning</title> + <para> + Every interface is versioned and every protocol object implements a + particular version of its interface. For global objects, the maximum + version supported by the server is advertised with the global and the + actual verion of the created protocol object is determined by the + version argument passed to wl_registry.bind(). For objects that are + not globals, their version is inferred from the object that created + them. + </para> + <para> + In order to keep things sane, this has a few implications for + interface versions: + <itemizedlist> + <listitem> + <para> + The object creation hierarchy must be a tree. Otherwise, + infering object versions from the parent object becomes a much + more difficult to properly track. + </para> + </listitem> + <listitem> + <para> + When the version of an interface increases, so does the version + of its parent (recursively until you get to a global interface) + </para> + </listitem> + <listitem> + <para> + A global interface's version number acts like a counter for all + of its child interfaces. Whenever a child interface gets + modified, the global parent's interface version number also + increases (see above). The child interface then takes on the + same version number as the new version of its parent global + interface. + </para> + </listitem> + </itemizedlist> + </para> + <para> + To illustrate the above, consider the wl_compositor interface. It + has two children, wl_surface and wl_region. As of wayland version + 1.2, wl_surface and wl_compositor are both at version 3. If + something is added to the wl_region interface, both wl_region and + wl_compositor will get bumpped to version 4. If, afterwards, + wl_surface is changed, both wl_compositor and wl_surface will be at + version 5. In this way the global interface version is used as a + sort of "counter" for all of its child interfaces. This makes it + very simple to know the version of the child given the version of its + parent. The child is at the highest possible interface version that + is less than or equal to its parent's version. + </para> + <para> + It is worth noting a particular exception to the above versioning + scheme. The wl_display (and, by extension, wl_registry) interface + cannot change because it is the core protocol object and its version + is never advertised nor is there a mechanism to request a different + version. + </para> + </section> <section id="sect-Protocol-Connect-Time"> <title>Connect Time</title> <para> -- 1.8.3.1 _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
