diff options
author | Jason Ekstrand <jason@jlekstrand.net> | 2013-08-18 16:53:54 -0500 |
---|---|---|
committer | Kristian Høgsberg <krh@bitplanet.net> | 2013-08-19 16:23:08 -0700 |
commit | 6b8eef962f4d662d64c46439fc7b09278ccf2e0d (patch) | |
tree | 6472528b6ef3dd17f118f5caae133e9ac74957bd /doc | |
parent | 52de02348287fbc3ed24c00f154b3d9cb45830e7 (diff) |
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 <jason@jlekstrand.net>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/publican/sources/Protocol.xml | 61 |
1 files changed, 61 insertions, 0 deletions
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 @@ </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> |