AcoSail/wayland
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

doc: Add a section on interface and protocol object versioning

Browse Source 
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>
This commit is contained in:
Jason Ekstrand 2013-08-18 16:53:54 -05:00 committed by Kristian Høgsberg
parent 52de023482
commit 6b8eef962f
1 changed files with 61 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
doc/publican/sources/Protocol.xml
View File

@ -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>