From 6b8eef962f4d662d64c46439fc7b09278ccf2e0d Mon Sep 17 00:00:00 2001 From: Jason Ekstrand Date: Sun, 18 Aug 2013 16:53:54 -0500 Subject: [PATCH] doc: Add a section on interface and protocol object versioning 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 --- 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 74f2aea..b79b6be 100644 --- a/doc/publican/sources/Protocol.xml +++ b/doc/publican/sources/Protocol.xml @@ -164,6 +164,67 @@ +
+ Versioning + + 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. + + + In order to keep things sane, this has a few implications for + interface versions: + + + + The object creation hierarchy must be a tree. Otherwise, + infering object versions from the parent object becomes a much + more difficult to properly track. + + + + + When the version of an interface increases, so does the version + of its parent (recursively until you get to a global interface) + + + + + 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. + + + + + + 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. + + + 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. + +
Connect Time -- 2.7.4