1063 lines
40 KiB
XML
1063 lines
40 KiB
XML
|
<?xml version="1.0" encoding="UTF-8" ?>
|
||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
||
|
|
||
|
<!--translated from sync.tex, on 2010-06-29 10:52:00,
|
||
|
by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,refcaption -->
|
||
|
|
||
|
|
||
|
<book id="sync">
|
||
|
|
||
|
<bookinfo>
|
||
|
<title>X Synchronization Extention Protocol</title>
|
||
|
<subtitle>X Consortium Standard</subtitle>
|
||
|
<releaseinfo>X Version 11, Release 6.6.84</releaseinfo>
|
||
|
<authorgroup>
|
||
|
<author>
|
||
|
<firstname>Tim</firstname><surname>Glauert</surname>
|
||
|
<affiliation><orgname>Olivetti Research/MultiWorks</orgname></affiliation>
|
||
|
</author>
|
||
|
<othercredit>
|
||
|
<firstname>Dave</firstname>
|
||
|
<surname>Carver</surname>
|
||
|
<affiliation><orgname>Digital EquipmentCorporation, MIT/Project Athena</orgname></affiliation>
|
||
|
</othercredit>
|
||
|
<othercredit>
|
||
|
<firstname>Jim</firstname>
|
||
|
<surname>Gettys</surname>
|
||
|
<affiliation><orgname>Digital EquipmentCorporation, Cambridge Research Laboratory</orgname></affiliation>
|
||
|
</othercredit>
|
||
|
<othercredit>
|
||
|
<firstname>David</firstname>
|
||
|
<surname>Wiggins</surname>
|
||
|
<affiliation><orgname>X Consortium, Inc.</orgname></affiliation>
|
||
|
</othercredit>
|
||
|
</authorgroup>
|
||
|
<corpname>X Consortium Standard</corpname>
|
||
|
|
||
|
<copyright>
|
||
|
<year>1991</year>
|
||
|
<holder>
|
||
|
Olivetti Research Limited, Cambridge England and
|
||
|
Digital Equipment Corporation, Maynard, Massachusetts
|
||
|
</holder>
|
||
|
</copyright>
|
||
|
<copyright><year>1991</year><holder>X Consortium</holder></copyright>
|
||
|
|
||
|
<releaseinfo>Version 3.0</releaseinfo>
|
||
|
<affiliation><orgname>X Consortium</orgname></affiliation>
|
||
|
<productnumber>X Version 11, Release 6.8</productnumber>
|
||
|
|
||
|
<legalnotice>
|
||
|
<para>
|
||
|
Permission to use, copy, modify, and distribute this documentation for any
|
||
|
purpose and without fee is hereby granted, provided that the above
|
||
|
copyright notice appear in all copies. Olivetti, Digital, MIT, and the
|
||
|
X Consortium make no representations about the suitability for any purpose
|
||
|
of the information in this document. This documentation is provided as
|
||
|
is without express or implied warranty.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
Permission is hereby granted, free of charge, to any person obtaining
|
||
|
a copy of this software and associated documentation files
|
||
|
(the "Software"), to deal in the Software without
|
||
|
restriction, including without limitation the rights to use, copy,
|
||
|
modify, merge, publish, distribute, sublicense, and/or sell copies of
|
||
|
the Software, and to permit persons to whom the Software is furnished
|
||
|
to do so, subject to the following conditions:
|
||
|
</para>
|
||
|
|
||
|
<para>The above copyright notice and this permission notice shall be included
|
||
|
in all copies or substantial portions of the Software.</para>
|
||
|
|
||
|
<para>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY
|
||
|
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
|
||
|
EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||
|
SOFTWARE.</para>
|
||
|
|
||
|
<para>Except as contained in this notice, the name of the X Consortium shall
|
||
|
not be used in advertising or otherwise to promote the sale, use or other
|
||
|
dealings in this Software without prior written authorization from the X
|
||
|
Consortium.</para>
|
||
|
</legalnotice>
|
||
|
|
||
|
</bookinfo>
|
||
|
|
||
|
<chapter id="synchronization_protocol">
|
||
|
<title>Synchronization Protocol</title>
|
||
|
<para>
|
||
|
The core X protocol makes no guarantees about the relative order of execution
|
||
|
of requests for different clients. This means that any synchronization between
|
||
|
clients must be done at the client level in an operating system-dependent and
|
||
|
network-dependent manner. Even if there was an accepted standard for such
|
||
|
synchronization, the use of a network introduces unpredictable delays between
|
||
|
the synchronization of the clients and the delivery of the resulting requests
|
||
|
to the X server.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The core X protocol also makes no guarantees about the time at which requests
|
||
|
are executed, which means that all clients with real-time constraints must
|
||
|
implement their timing on the host computer. Any such timings are subject to
|
||
|
error introduced by delays within the operating system and network and are
|
||
|
inefficient because of the need for round-trip requests that keep the client
|
||
|
and server synchronized.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The synchronization extension provides primitives that allow synchronization
|
||
|
between clients to take place entirely within the X server. This removes any
|
||
|
error introduced by the network and makes it possible to synchronize clients
|
||
|
on different hosts running different operating systems. This is important for
|
||
|
multimedia applications, where audio, video, and graphics data streams are
|
||
|
being synchronized. The extension also provides internal timers within the
|
||
|
X server to which client requests can be synchronized. This allows simple
|
||
|
animation applications to be implemented without any round-trip requests and
|
||
|
makes best use of buffering within the client, network, and server.
|
||
|
</para>
|
||
|
|
||
|
<sect1 id="description">
|
||
|
<title>Description</title>
|
||
|
<para>
|
||
|
The mechanism used by this extension for synchronization within the X
|
||
|
server is to block the processing of requests from a client until a
|
||
|
specific synchronization condition occurs. When the condition occurs, the
|
||
|
client is released and processing of requests continues. Multiple clients
|
||
|
may block on the same condition to give inter-client synchronization.
|
||
|
Alternatively, a single client may block on a condition such as an animation
|
||
|
frame marker.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The extension adds <function>Counter</function> and
|
||
|
<function>Alarm</function> to the set of resources managed by the
|
||
|
server. A counter has a 64-bit integer value that may be increased or
|
||
|
decreased by client requests or by the server internally. A client can block
|
||
|
by sending an Await request that waits until one of a set of synchronization
|
||
|
conditions, called TRIGGERs, becomes TRUE.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The <function>CreateCounter</function> request allows a client to create a
|
||
|
<function>Counter</function> that can be changed by explicit
|
||
|
<function>SetCounter</function> and <function>ChangeCounter</function>
|
||
|
requests. These can be used to implement synchronization between different
|
||
|
clients.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
There are some counters, called <function>System Counters</function>, that
|
||
|
are changed by the server internally rather than by client requests. The
|
||
|
effect of any change to a system counter is not visible until the server
|
||
|
has finished processing the current request. In other words, system
|
||
|
counters are apparently updated in the gaps between the execution of
|
||
|
requests rather than during the actual execution of a request. The extension
|
||
|
provides a system counter that advances with the server time as defined by
|
||
|
the core protocol, and it may also provide counters that advance with the
|
||
|
real-world time or that change each time the CRT screen is refreshed.
|
||
|
Other extensions may provide their own extension-specific system counters.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The extension provides an <function>Alarm</function> mechanism that allows
|
||
|
clients to receive an event on a regular basis when a particular counter
|
||
|
is changed.
|
||
|
</para>
|
||
|
|
||
|
</sect1>
|
||
|
<sect1 id="types">
|
||
|
<title>Types</title>
|
||
|
<para>
|
||
|
Please refer to the X11 Protocol specification as this document uses
|
||
|
syntactic conventions established there and references types defined there.
|
||
|
</para>
|
||
|
|
||
|
<para>The following new types are used by the extension.</para>
|
||
|
|
||
|
<literallayout class="monospaced">
|
||
|
INT64: 64-bit signed integer
|
||
|
COUNTER: XID
|
||
|
VALUETYPE: {Absolute,Relative};
|
||
|
TESTTYPE: {PositiveTransition,NegativeTransition,
|
||
|
PositiveComparison,NegativeComparison}
|
||
|
TRIGGER: [
|
||
|
counter:COUNTER,
|
||
|
value-type:VALUETYPE,
|
||
|
wait-value:INT64,
|
||
|
test-type:TESTTYPE
|
||
|
]
|
||
|
WAITCONDITION: [
|
||
|
trigger:TRIGGER,
|
||
|
event-threshold:INT64
|
||
|
]
|
||
|
SYSTEMCOUNTER: [
|
||
|
name:STRING8,
|
||
|
counter:COUNTER,
|
||
|
resolution:INT64
|
||
|
]
|
||
|
ALARM: XID
|
||
|
ALARMSTATE: {Active,Inactive,Destroyed}
|
||
|
</literallayout>
|
||
|
|
||
|
<para>
|
||
|
The COUNTER type defines the client-side handle on a server
|
||
|
<function>Counter</function>. The value of a counter is an INT64.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The TRIGGER type defines a test on a counter that is either TRUE or FALSE. The
|
||
|
value of the test is determined by the combination of a test value, the value
|
||
|
of the counter, and the specified test-type.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The test value for a trigger is calculated using the value-type and
|
||
|
wait-value fields when the trigger is initialized. If the value-type field
|
||
|
is not one of the named VALUETYPE constants, the request that initialized the
|
||
|
trigger will return a <function>Value</function> error. If the value-type
|
||
|
field is <function>Absolute</function>, the test value is given by the
|
||
|
wait-value field. If the value-type field is <function>Relative</function>,
|
||
|
the test value is obtained by adding the wait-value field to the value of the
|
||
|
counter. If the resulting test value would lie outside the range for an
|
||
|
INT64, the request that initialized the trigger will return a
|
||
|
<function>Value</function> error. If counter is <function>None</function>
|
||
|
and the value-type is <function>Relative</function>, the request that
|
||
|
initialized the trigger will return a <function>Match</function> error. If
|
||
|
counter is not None and does not name a valid counter, a Counter error is
|
||
|
generated.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
If the test-type is <function>PositiveTransition</function>, the trigger is
|
||
|
initialized to FALSE, and it will become TRUE when the counter changes from
|
||
|
a value less than the test value to a value greater than or equal to the
|
||
|
test value. If the test-type is <function>NegativeTransition</function>,
|
||
|
the trigger is initialize to FALSE, and it will become TRUE when the counter
|
||
|
changes from a value greater than the test value to a value less than or
|
||
|
equal to the test value. If the test-type is
|
||
|
<function>PositiveComparison</function>, the trigger is TRUE if the
|
||
|
counter is greater than or equal to the test value and FALSE otherwise. If the
|
||
|
test-type is <function>NegativeComparison</function>, the trigger is TRUE
|
||
|
if the counter is less than or equal to the test value and FALSE otherwise.
|
||
|
If the test-type is not one of the named TESTTYPE constants, the request that
|
||
|
initialized the trigger will return a Value error. A trigger with a counter
|
||
|
value of <function>None</function> and a valid test-type is always TRUE.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The WAITCONDITION type is simply a trigger with an associated event-threshold.
|
||
|
The event threshold is used by the <function>Await</function> request to
|
||
|
decide whether or not to generate an event to the client after the trigger has
|
||
|
become TRUE. By setting the event-threshold to an appropriate value, it is
|
||
|
possible to detect the situation where an <function>Await</function> request
|
||
|
was processed after the TRIGGER became TRUE, which usually indicates that
|
||
|
the server is not processing requests as fast as the client expects.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The SYSTEMCOUNTER type provides the client with information about a
|
||
|
<function>System</function>Counter. The name field is the textual name of
|
||
|
the counter that identifies the counter to the client. The counter field
|
||
|
is the client-side handle that should be used in requests that require a
|
||
|
counter. The resolution field gives the approximate step size of the system
|
||
|
counter. This is a hint to the client
|
||
|
that the extension may not be able to resolve two wait conditions with test
|
||
|
values that differ by less than this step size. A microsecond clock, for
|
||
|
example, may advance in steps of 64 microseconds, so a counter based on this
|
||
|
clock would have a resolution of 64.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
The only system counter that is guaranteed to be present is called SERVERTIME,
|
||
|
which counts milliseconds from some arbitrary starting point. The least
|
||
|
significant 32 bits of this counter track the value of Time used by the
|
||
|
server in Events and Requests. Other system counters may be provided by
|
||
|
different implementations of the extension. The X Consortium will maintain a
|
||
|
registry of system counter names to avoid collisions in the name space.
|
||
|
</para>
|
||
|
|
||
|
<para>
|
||
|
An ALARM is the client-side handle on an <function>Alarm</function> resource.
|
||
|
</para>
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="errors">
|
||
|
<title>Errors</title>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>Counter</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
This error is generated if the value for a COUNTER argument in a request
|
||
|
does not name a defined COUNTER.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>Alarm</term>
|
||
|
<listitem>
|
||
|
<para>
|
||
|
This error is generated if the value for an ALARM argument in a request
|
||
|
does not name a defined ALARM.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
|
||
|
</sect1>
|
||
|
<sect1 id="requests">
|
||
|
|
||
|
<title>Requests</title>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>Initialize</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
version-major,version-minor: CARD8
|
||
|
=>
|
||
|
version-major,version-minor: CARD8
|
||
|
</literallayout>
|
||
|
|
||
|
<para>
|
||
|
This request must be executed before any other requests for this extension. If a
|
||
|
client violates this rule, the results of all SYNC requests that it issues are
|
||
|
undefined. The request takes the version number of the extension that the
|
||
|
client wishes to use and returns the actual version number being implemented
|
||
|
by the extension for this client. The extension may return different
|
||
|
version numbers to a client depending of the version number supplied by
|
||
|
that client. This request should be executed only once for each client
|
||
|
connection.
|
||
|
</para>
|
||
|
<para>
|
||
|
Given two different versions of the SYNC protocol, v1 and v2, v1 is
|
||
|
compatible with v2 if and only if v1.version_major = v2.version_major
|
||
|
and v1.version_minor <= v2.version_minor. Compatible means that the
|
||
|
functionality is fully supported in an identical fashion in the two versions.
|
||
|
</para>
|
||
|
<para>
|
||
|
This document describes major version 3, minor version 0 of the SYNC protocol.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>ListSystemCounters</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
=>
|
||
|
system-counters: LISTofSYSTEMCOUNTER
|
||
|
Errors: Alloc
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request returns a list of all the system counters that are available at
|
||
|
the time the request is executed, which includes the system counters
|
||
|
that are maintained by other extensions. The list returned by this
|
||
|
request may change as counters are created and destroyed by other extensions.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>CreateCounter</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
id: COUNTER
|
||
|
initial-value: INT64
|
||
|
Errors: IDChoice,Alloc
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request creates a counter and assigns the specified id to it. The counter
|
||
|
value is initialized to the specified initial-value and there are no clients
|
||
|
waiting on the counter.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>DestroyCounter</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
counter: COUNTER
|
||
|
Errors: Counter,Access
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request destroys the given counter and sets the counter fields for all
|
||
|
triggers that specify this counter to <function>None</function>. All clients
|
||
|
waiting on the counter are released and a <function>CounterNotify</function>
|
||
|
event with the destroyed field set to TRUE is sent to each waiting client,
|
||
|
regardless of the event-threshold. All alarms specifying the counter become
|
||
|
<function>Inactive</function> and an <function>AlarmNotify</function>
|
||
|
event with a state field of <function>Inactive</function> is generated. A
|
||
|
counter is destroyed automatically when the connection to the creating client
|
||
|
is closed down if the close-down mode is Destroy. An
|
||
|
<function>Access</function> error is generated if counter is a system
|
||
|
counter. A <function>Counter</function> error is generated if counter does
|
||
|
not name a valid counter.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>QueryCounter</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
counter: COUNTER
|
||
|
=>
|
||
|
value: INT64
|
||
|
Errors: <function>Counter</function>
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request returns the current value of the given counter or a generates
|
||
|
Counter error if counter does not name a valid counter.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>Await</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
wait-list: LISTofWAITCONDITION
|
||
|
Errors: Counter,Alloc,Value
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
When this request is executed, the triggers in the wait-list are initialized
|
||
|
using the wait-value and value-type fields, as described in the definition of
|
||
|
TRIGGER above. The processing of further requests for the client is blocked
|
||
|
until one or more of the triggers becomes TRUE. This may happen immediately,
|
||
|
as a result of the initialization, or at some later time, as a result of
|
||
|
a subsequent <function>SetCounter</function>,
|
||
|
<function>ChangeCounter</function> or
|
||
|
<function>DestroyCounter</function> request.
|
||
|
</para>
|
||
|
<para>
|
||
|
A Value error is generated if wait-list is empty.
|
||
|
</para>
|
||
|
<para>
|
||
|
When the client becomes unblocked, each trigger is checked to determine
|
||
|
whether a <function>CounterNotify</function> event should be generated.
|
||
|
The difference between the counter and the test value is calculated by
|
||
|
subtracting the test value from the value of the counter. If the test-type
|
||
|
is <function>PositiveTransition</function> or
|
||
|
<function>PositiveComparison</function>, a
|
||
|
<function>CounterNotify</function> event is generated if the difference is
|
||
|
at least event-threshold. If the test-type is
|
||
|
<function>NegativeTransition</function> or
|
||
|
<function>NegativeComparison</function>, a
|
||
|
<function>CounterNotify</function> event is generated if the difference
|
||
|
is at most event-threshold. If the difference lies outside the range for an
|
||
|
INT64, an event is not generated.
|
||
|
</para>
|
||
|
<para>
|
||
|
This threshold check is made for each trigger in the list and a
|
||
|
<function>CounterNotify</function> event is generated for every trigger for
|
||
|
which the check succeeds. The check for
|
||
|
<function>CounterNotify</function> events is performed even if one of the
|
||
|
triggers is TRUE when the request is first executed. Note that a
|
||
|
<function>CounterNotify</function> event may be generated for a trigger
|
||
|
that is FALSE if there are multiple triggers in the request. A
|
||
|
<function>CounterNotify</function> event with the destroyed flag set to
|
||
|
TRUE is always generated if the counter for one of the triggers is
|
||
|
destroyed.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>ChangeCounter</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
counter: COUNTER
|
||
|
amount: INT64
|
||
|
Errors: <function>Counter,Access,Value</function>
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request changes the given counter by adding amount to the current
|
||
|
counter value. If the change to this counter satisfies a trigger for which a client
|
||
|
is waiting, that client is unblocked and one or more
|
||
|
<function>CounterNotify</function> events may be generated. If the change to
|
||
|
the counter satisfies the trigger for an alarm, an
|
||
|
<function>AlarmNotify</function> event is generated and the
|
||
|
alarm is updated. An <function>Access</function> error is generated if
|
||
|
counter is a system counter. A <function>Counter</function> error is
|
||
|
generated if counter does not name a valid counter. If the resulting value
|
||
|
for the counter would be outside the range for an INT64, a
|
||
|
<function>Value</function> error is generated and the counter is not changed.
|
||
|
</para>
|
||
|
<para>
|
||
|
It should be noted that all the clients whose triggers are satisfied by this
|
||
|
change are unblocked, so this request cannot be used to implement mutual
|
||
|
exclusion.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>SetCounter</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
counter: COUNTER
|
||
|
value: INT64
|
||
|
Errors: <function>Counter,Access</function>
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request sets the value of the given counter to value. The effect is
|
||
|
equivalent to executing the appropriate ChangeCounter request to change
|
||
|
the counter value to value. An Access error is generated if counter names a
|
||
|
system counter. A Counter error is generated if counter does not name a valid
|
||
|
counter.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>CreateAlarm</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
id: ALARM
|
||
|
values-mask: CARD32
|
||
|
values-list: LISTofVALUE
|
||
|
left">Errors: IDChoice,Counter,Match,Value,Alloc
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request creates an alarm and assigns the identifier id to it. The
|
||
|
values-mask and values-list specify the attributes that are to be explicitly
|
||
|
initialized. The attributes for an Alarm and their defaults are:
|
||
|
</para>
|
||
|
<informaltable>
|
||
|
<tgroup cols="4">
|
||
|
<colspec colname="c1"/>
|
||
|
<colspec colname="c2"/>
|
||
|
<colspec colname="c3"/>
|
||
|
<colspec colname="c4"/>
|
||
|
<tbody>
|
||
|
<row>
|
||
|
<entry align="left">Attribute</entry>
|
||
|
<entry align="left">Type</entry>
|
||
|
<entry align="left">Default</entry>
|
||
|
</row>
|
||
|
<row role="hline">
|
||
|
<entry rowsep="1"></entry>
|
||
|
<entry rowsep="1"></entry>
|
||
|
<entry rowsep="1"></entry>
|
||
|
<entry rowsep="1"></entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry align="left">trigger</entry>
|
||
|
<entry align="left">TRIGGER</entry>
|
||
|
<entry align="left">counter</entry>
|
||
|
<entry align="left">None</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry align="left"></entry>
|
||
|
<entry align="left"></entry>
|
||
|
<entry align="left">value-type</entry>
|
||
|
<entry align="left">Absolute</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry align="left"></entry>
|
||
|
<entry align="left"></entry>
|
||
|
<entry align="left">value</entry>
|
||
|
<entry align="left">0</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry align="left"></entry>
|
||
|
<entry align="left"></entry>
|
||
|
<entry align="left">test-type</entry>
|
||
|
<entry align="left">PositiveComparison</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry align="left">delta</entry>
|
||
|
<entry align="left">INT64</entry>
|
||
|
<entry align="left">1</entry>
|
||
|
</row>
|
||
|
<row>
|
||
|
<entry align="left">events</entry>
|
||
|
<entry align="left">BOOL</entry>
|
||
|
<entry align="left">TRUE</entry>
|
||
|
</row>
|
||
|
</tbody>
|
||
|
</tgroup>
|
||
|
</informaltable>
|
||
|
<para>
|
||
|
The trigger is initialized as described in the definition of TRIGGER, with an
|
||
|
error being generated if necessary.
|
||
|
</para>
|
||
|
<para>
|
||
|
If the counter is <function>None</function>, the state of the alarm is set
|
||
|
to <function>Inactive</function>, else it is set to Active.
|
||
|
</para>
|
||
|
<para>
|
||
|
Whenever the trigger becomes TRUE, either as a result of this request or as the
|
||
|
result of a <function>SetCounter</function>,
|
||
|
<function>ChangeCounter</function>, <function>DestroyCounter</function>, or
|
||
|
<function>ChangeAlarm</function> request, an
|
||
|
<function>AlarmNotify</function> event is generated and the alarm is
|
||
|
updated. The alarm is updated by repeatedly adding delta to the value of the
|
||
|
trigger and reinitializing it until it becomes FALSE. If this update would
|
||
|
cause value to fall outside the range for an INT64, or if the counter
|
||
|
value is <function>None</function>, or if the delta is 0 and test-type
|
||
|
is <function>PositiveComparison</function> or
|
||
|
<function>NegativeComparison</function>, no change is made to value and
|
||
|
the alarm state is changed to <function>Inactive</function> before the
|
||
|
event is generated. No further events are generated by an
|
||
|
<function>Inactive</function> alarm until a <function>ChangeAlarm</function>
|
||
|
or <function>DestroyAlarm </function> request is executed.
|
||
|
</para>
|
||
|
<para>
|
||
|
If the test-type is <function>PositiveComparison</function> or
|
||
|
<function>PositiveTransition and</function> delta is less than zero, or
|
||
|
if the test-type is <function>NegativeComparison</function> or
|
||
|
<function>NegativeTransition</function> and delta is greater than zero,
|
||
|
a <function>Match</function> error is generated.
|
||
|
</para>
|
||
|
<para>
|
||
|
The events value enables or disables delivery of
|
||
|
<function>AlarmNotify</function> events
|
||
|
to the requesting client. The alarm keeps a separate event flag for
|
||
|
each client so that other clients may select to receive events from this
|
||
|
alarm.
|
||
|
</para>
|
||
|
<para>
|
||
|
An <function>AlarmNotify</function> event is always generated at some time
|
||
|
after the execution of a <function>CreateAlarm</function> request. This
|
||
|
will happen immediately if the trigger is TRUE, or it will happen later
|
||
|
when the trigger becomes TRUE or the Alarm is destroyed.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>ChangeAlarm</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
id: ALARM
|
||
|
values-mask: CARD32
|
||
|
values-list: LISTofVALUE
|
||
|
Errors: Alarm,Counter,Value,Match
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request changes the parameters of an Alarm. All of the parameters
|
||
|
specified for the <function>CreateAlarm</function> request may be changed
|
||
|
using this request. The trigger is reinitialized and an
|
||
|
<function>AlarmNotify</function> event is generated if appropriate, as
|
||
|
explained in the description of the <function>CreateAlarm</function> request.
|
||
|
</para>
|
||
|
<para>
|
||
|
Changes to the events flag affect the event delivery to the requesting
|
||
|
client only and may be used by a client to select or deselect event delivery
|
||
|
from an alarm created by another client.
|
||
|
</para>
|
||
|
<para>
|
||
|
The order in which attributes are verified and altered is server-dependent.
|
||
|
If an error is generated, a subset of the attributes may have been altered.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>DestroyAlarm</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
alarm: ALARM
|
||
|
Errors: Alarm
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request destroys an alarm. An alarm is automatically destroyed when the
|
||
|
creating client is closed down if the close-down mode is
|
||
|
<function>Destroy</function>. When an alarm is destroyed, an
|
||
|
<function>AlarmNotify</function> event is generated with a state value of
|
||
|
<function>Destroyed</function>.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>QueryAlarm</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
alarm: ALARM
|
||
|
=>
|
||
|
trigger: TRIGGER
|
||
|
delta: INT64
|
||
|
events: ALARMEVENTMASK
|
||
|
state: ALARMSTATE
|
||
|
Errors: <function>Alarm</function>
|
||
|
</literallayout>
|
||
|
<para>This request retrieves the current parameters for an Alarm.</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>SetPriority</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
client-resource: XID
|
||
|
priority: INT32
|
||
|
Errors: <function>Match</function>
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request changes the scheduling priority of the client that created
|
||
|
client-resource. If client-resource is <function>None</function>, then
|
||
|
the priority for the client making the request is changed. A
|
||
|
<function>Match</function> error is generated if client-resource is not
|
||
|
<function>None</function> and does not name an existing resource in the
|
||
|
server. For any two priority values, A and B, A is higher priority if
|
||
|
and only if A is greater than B.
|
||
|
</para>
|
||
|
<para>
|
||
|
The priority of a client is set to 0 when the initial client connection is
|
||
|
made.
|
||
|
</para>
|
||
|
<para>
|
||
|
The effect of different client priorities depends on the particular
|
||
|
implementation of the extension, and in some cases it may have no effect at
|
||
|
all. However, the intention is that higher priority clients will have
|
||
|
their requests executed before those of lower priority clients.
|
||
|
</para>
|
||
|
<para>
|
||
|
For most animation applications, it is desirable that animation clients be
|
||
|
given priority over nonrealtime clients. This improves the smoothness of the
|
||
|
animation on a loaded server. Because a server is free to implement very strict
|
||
|
priorities, processing requests for the highest priority client to the
|
||
|
exclusion of all others, it is important that a client that may potentially
|
||
|
monopolize the whole server, such as an animation that produces continuous
|
||
|
output as fast as it can with no rate control, is run at low rather than high
|
||
|
priority.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>GetPriority</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
client-resource: XID
|
||
|
=>
|
||
|
priority: INT32
|
||
|
Errors: <function>Match</function>
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
This request returns the scheduling priority of the client that created
|
||
|
client-resource. If client-resource is <function>None</function>, then the
|
||
|
priority for the client making the request is returned. A
|
||
|
<function>Match</function> error is generated if client-resource is
|
||
|
not <function>None</function> and does not name an existing resource in the
|
||
|
server.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="events">
|
||
|
<title>Events</title>
|
||
|
|
||
|
<variablelist>
|
||
|
<varlistentry>
|
||
|
<term>CounterNotify</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
counter: COUNTER
|
||
|
wait-value: INT64
|
||
|
counter-value: INT64
|
||
|
time: TIME
|
||
|
count: CARD16
|
||
|
destroyed: BOOL
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
<function>CounterNotify</function> events may be generated when a client
|
||
|
becomes unblocked after an <function>Await</function> request has been
|
||
|
processed. The wait-value is the value being waited for, and counter-value
|
||
|
is the actual value of the counter at the time the event was generated.
|
||
|
The destroyed flag is TRUE if this request was generated as the result of
|
||
|
the destruction of the counter and FALSE otherwise. The time is the server
|
||
|
time at which the event was generated.
|
||
|
</para>
|
||
|
<para>
|
||
|
When a client is unblocked, all the <function>CounterNotify</function>
|
||
|
events for the Await request are generated contiguously. If count is 0,
|
||
|
there are no more events to follow for this request. If count is n,
|
||
|
there are at least n more events to follow.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
<varlistentry>
|
||
|
<term>AlarmNotify</term>
|
||
|
<listitem>
|
||
|
<literallayout class="monospaced">
|
||
|
alarm: ALARM
|
||
|
counter-value: INT64
|
||
|
alarm-value: INT64
|
||
|
state: ALARMSTATE
|
||
|
time: TIME
|
||
|
</literallayout>
|
||
|
<para>
|
||
|
An <function>AlarmNotify</function> event is generated when an alarm is
|
||
|
triggered. alarm-value is the test value of the trigger in the alarm when
|
||
|
it was triggered, counter-value is the value of the counter that triggered
|
||
|
the alarm, and time is the server time at which the event was generated.
|
||
|
The state is the new state of the alarm. If state is
|
||
|
<function>Inactive</function>, no more events will be generated by this
|
||
|
alarm until a <function>ChangeAlarm</function> request is executed, the alarm
|
||
|
is destroyed, or the counter for the alarm is destroyed.
|
||
|
</para>
|
||
|
</listitem>
|
||
|
</varlistentry>
|
||
|
</variablelist>
|
||
|
</sect1>
|
||
|
</chapter>
|
||
|
|
||
|
<chapter id="encoding">
|
||
|
<title>Encoding</title>
|
||
|
<para>
|
||
|
Please refer to the X11 Protocol Encoding document as this section uses
|
||
|
syntactic conventions established there and references types defined there.
|
||
|
</para>
|
||
|
<para>The name of this extension is "SYNC".</para>
|
||
|
|
||
|
<sect1 id="encoding_new_types">
|
||
|
<title>Encoding New Types</title>
|
||
|
<para>
|
||
|
The following new types are used by the extension.
|
||
|
</para>
|
||
|
|
||
|
<literallayout class="monospaced">
|
||
|
ALARM: CARD32
|
||
|
ALARMSTATE:
|
||
|
0 Active
|
||
|
1 Inactive
|
||
|
2 Destroyed
|
||
|
COUNTER: CARD32
|
||
|
INT64: 64-bit signed integer
|
||
|
SYSTEMCOUNTER:
|
||
|
4 COUNTER counter
|
||
|
8 INT64 resolution
|
||
|
2 n length of name in bytes
|
||
|
n STRING8 name
|
||
|
p pad,p=pad(n+2)
|
||
|
TESTTYPE:
|
||
|
0 PositiveTransition
|
||
|
1 NegativeTransition
|
||
|
2 PositiveComparison
|
||
|
3 NegativeComparison
|
||
|
TRIGGER:
|
||
|
4 COUNTER counter
|
||
|
4 VALUETYPE wait-type
|
||
|
8 INT64 wait-value
|
||
|
4 TESTTYPE test-type VALUETYPE:
|
||
|
0 Absolute
|
||
|
1 Relative
|
||
|
WAITCONDITION:
|
||
|
20 TRIGGER trigger
|
||
|
8 INT64 event threshold
|
||
|
</literallayout>
|
||
|
|
||
|
<para>
|
||
|
An INT64 is encoded in 8 bytes with the most significant 4 bytes
|
||
|
first followed by the least significant 4 bytes. Within these 4-byte
|
||
|
groups, the byte ordering determined during connection setup is used.
|
||
|
</para>
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="encoding_errors">
|
||
|
<title>Encoding Errors</title>
|
||
|
<literallayout class="monospaced">
|
||
|
<function>Counter</function>
|
||
|
1 0 Error
|
||
|
1 Base + 0 code
|
||
|
2 CARD16 sequence number
|
||
|
4 CARD32 bad counter
|
||
|
2 CARD16 minor opcode
|
||
|
1 CARD8 major opcode
|
||
|
21 unused
|
||
|
<function>Alarm</function>
|
||
|
1 0 Error
|
||
|
1 Base + 1 code
|
||
|
2 CARD16 sequence number
|
||
|
4 CARD32 bad alarm
|
||
|
2 CARD16 minor opcode
|
||
|
1 CARD8 major opcode
|
||
|
21 unused
|
||
|
</literallayout>
|
||
|
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="encoding_requests">
|
||
|
<title>Encoding Requests</title>
|
||
|
|
||
|
<literallayout class="monospaced">
|
||
|
<function>Initialize</function>
|
||
|
1 CARD8 major opcode
|
||
|
1 0 minor opcode
|
||
|
2 2 request length
|
||
|
1 CARD8 major version
|
||
|
1 CARD8 minor version
|
||
|
2 unused
|
||
|
=>
|
||
|
1 1 Reply
|
||
|
1 unused
|
||
|
2 CARD16 sequence number
|
||
|
4 0 reply length
|
||
|
1 CARD8 major version
|
||
|
1 CARD8 minor version
|
||
|
2 unused
|
||
|
20 unused
|
||
|
|
||
|
<function>ListSystemCounters</function>
|
||
|
1 CARD8 major opcode
|
||
|
1 1 minor opcode
|
||
|
2 1 request length
|
||
|
=>
|
||
|
1 1 Reply
|
||
|
1 unused
|
||
|
2 CARD16 sequence number
|
||
|
4 0 reply length
|
||
|
4 INT32 list length
|
||
|
20 unused
|
||
|
4n list of SYSTEMCOUNTER system counters
|
||
|
|
||
|
<function>CreateCounter</function>
|
||
|
1 CARD8 major opcode
|
||
|
1 2 minor opcode
|
||
|
2 4 request length
|
||
|
4 COUNTER id
|
||
|
8 INT64 initial value
|
||
|
|
||
|
<function>DestroyCounter</function>
|
||
|
1 CARD8 major opcode
|
||
|
1 6 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode</para></footnote>
|
||
|
2 2 request length
|
||
|
4 COUNTER counter
|
||
|
=>
|
||
|
1 1 Reply
|
||
|
1 unused
|
||
|
2 CARD16 sequence number
|
||
|
4 0 reply length
|
||
|
8 INT64 counter value
|
||
|
16 unused
|
||
|
|
||
|
Await
|
||
|
1 CARD8 major opcode
|
||
|
1 7 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote>
|
||
|
2 1 + 7*n request length
|
||
|
28n LISTofWAITCONDITION wait conditions
|
||
|
|
||
|
ChangeCounter
|
||
|
1 CARD8 major opcode
|
||
|
1 4 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote>
|
||
|
2 4 request length
|
||
|
4 COUNTER counter
|
||
|
8 INT64 amount
|
||
|
|
||
|
SetCounter
|
||
|
1 CARD8 major opcode
|
||
|
1 3 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote>
|
||
|
2 4 request length
|
||
|
4 COUNTER counter
|
||
|
8 INT64 value
|
||
|
|
||
|
CreateAlarm
|
||
|
1 CARD8 major opcode
|
||
|
1 8 minor opcode
|
||
|
2 3+n request length
|
||
|
4 ALARM id
|
||
|
4 BITMASK values mask
|
||
|
|
||
|
#x00000001 counter
|
||
|
#x00000002 value-type
|
||
|
#x00000004 value
|
||
|
#x00000008 test-type
|
||
|
#x00000010 delta
|
||
|
#x00000020 events
|
||
|
|
||
|
4n LISTofVALUE values
|
||
|
|
||
|
VALUES
|
||
|
4 COUNTER counter
|
||
|
4 VALUETYPE value-type
|
||
|
8 INT64 value
|
||
|
4 TESTTYPE test-type
|
||
|
8 INT64 delta
|
||
|
4 BOOL events
|
||
|
|
||
|
ChangeAlarm
|
||
|
1 CARD8 major opcode
|
||
|
1 9 minor opcode
|
||
|
2 3+n request length
|
||
|
4 ALARM id
|
||
|
4 BITMASK values mask
|
||
|
encodings as for <function>CreateAlarm</function>
|
||
|
4n LISTofVALUE values
|
||
|
encodings as for <function>CreateAlarm</function>
|
||
|
|
||
|
DestroyAlarm
|
||
|
1 CARD8 major opcode
|
||
|
1 11 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote>
|
||
|
2 2 request length
|
||
|
4 ALARM alarm
|
||
|
|
||
|
QueryAlarm
|
||
|
1 CARD8 major opcode
|
||
|
1 10 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote>
|
||
|
2 2 request length
|
||
|
4 ALARM alarm
|
||
|
=>
|
||
|
1 1 Reply
|
||
|
1 unused
|
||
|
2 CARD16 sequence number
|
||
|
4 2 reply length
|
||
|
20 TRIGGER trigger
|
||
|
8 INT64 delta
|
||
|
1 BOOL events
|
||
|
1 ALARMSTATE state
|
||
|
2 unused
|
||
|
|
||
|
SetPriority
|
||
|
1 CARD8 major opcode
|
||
|
1 12 minor opcode
|
||
|
2 3 request length
|
||
|
4 CARD32 id
|
||
|
4 INT32 priority
|
||
|
|
||
|
GetPriority
|
||
|
1 CARD8 major opcode
|
||
|
1 13 minor opcode
|
||
|
2 1 request length
|
||
|
4 CARD32 id
|
||
|
=>
|
||
|
1 1 Reply
|
||
|
1 unused
|
||
|
2 CARD16 sequence number
|
||
|
4 0 reply length
|
||
|
4 INT32 priority
|
||
|
20 unused
|
||
|
|
||
|
</literallayout>
|
||
|
|
||
|
</sect1>
|
||
|
|
||
|
<sect1 id="encoding_events">
|
||
|
<title>Encoding Events</title>
|
||
|
|
||
|
<literallayout class="monospaced">
|
||
|
<function>CounterNotify</function>
|
||
|
1 Base + 0 code
|
||
|
1 0 kind
|
||
|
2 CARD16 sequence number
|
||
|
4 COUNTER counter
|
||
|
8 INT64 wait value
|
||
|
8 INT64 counter value
|
||
|
4 TIME timestamp
|
||
|
2 CARD16 count
|
||
|
1 BOOL destroyed
|
||
|
1 unused
|
||
|
|
||
|
<function>AlarmNotify</function>
|
||
|
1 Base + 1 code
|
||
|
1 1 kind
|
||
|
2 CARD16 sequence number
|
||
|
4 ALARM alarm
|
||
|
8 INT64 counter value
|
||
|
8 INT64 alarm value
|
||
|
4 TIME timestamp
|
||
|
1 ALARMSTATE state
|
||
|
3 unused
|
||
|
</literallayout>
|
||
|
</sect1>
|
||
|
</chapter>
|
||
|
</book>
|