[Xcb] [doc] first step of the documentation of sync.xml
Jeremy Kolb
jkolb at brandeis.edu
Mon Dec 3 05:22:58 PST 2007
I only looked at the XML and I really like what I see.
Jeremy
Vincent Torri wrote:
>
> Hey,
>
> I have attached a patch that adds the documentation of the sync
> extension to the xml description. Actually, I have not added the doc to
> all the requests/types, as I first want your opinion about what I
> already added.
>
> I have also attached the xml description itself and the documentation of
> the sync protocol in TeX and Postscript.
>
> Please give your comments, advices etc...
>
> Thomas : I think that you can try to parse it and add Doxygen
> documentation in the header file.
>
> Vincent
>
>
> ------------------------------------------------------------------------
>
> diff --git a/src/sync.xml b/src/sync.xml
> index 74281f1..bc34232 100644
> --- a/src/sync.xml
> +++ b/src/sync.xml
> @@ -11,9 +11,17 @@ for licensing information.
> <xidtype name="ALARM" />
>
> <enum name="ALARMSTATE">
> - <item name="Active" />
> - <item name="Inactive" />
> - <item name="Destroyed" />
> + <doc>
> + <brief>
> + The ALARMSTATE type describe the state of an alarm.
> + </brief>
> + <detailed>
> + The ALARMSTATE type describe the state of an alarm.
> + </detailed>
> + </doc>
> + <item name="Active" doc="The alarm is active." />
> + <item name="Inactive" doc="The alarm is inactive." />
> + <item name="Destroyed" doc="The alarm is destroyed." />
> </enum>
>
> <xidtype name="COUNTER" />
> @@ -45,10 +53,38 @@ for licensing information.
> </struct>
>
> <struct name="SYSTEMCOUNTER">
> - <field type="COUNTER" name="counter" />
> + <doc>
> + <brief>
> + The SYSTEMCOUNTER type provides the client with information
> + about a System Counter.
> + </brief>
> + <detailed>
> + The SYSTEMCOUNTER type provides the client with information
> + about a System 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.
> +
> + 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.
> + </detailed>
> + </doc>
> + <field type="COUNTER" name="counter" doc="The counter." />
> <field type="INT64" name="resolution" />
> - <field type="CARD16" name="name_len" />
> - <list type="CARD8" name="name">
> + <field type="CARD16" name="name_len" doc="The length of the name of the counter" />
> + <list type="CARD8" name="name" doc=" The textual name of the counter" >
> <fieldref>name_len</fieldref>
> </list>
> </struct>
> @@ -61,73 +97,205 @@ for licensing information.
> </struct>
>
> <struct name="WAITCONDITION">
> - <field type="TRIGGER" name="trigger" />
> - <field type="INT64" name="event_threshold" />
> + <doc>
> + <brief>
> + The WAITCONDITION type is simply a trigger with an associated
> + event-threshold.
> + </brief>
> + <detailed>
> + The WAITCONDITION type is simply a trigger with an associated
> + event-threshold. The event threshold is used by the Await
> + 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 Await request was processed after
> + the TRIGGER became TRUE, which usually indicates that the server
> + is not processing requests as fast as the client expects.
> + </detailed>
> + </doc>
> + <field type="TRIGGER" name="trigger" doc="The trigger." />
> + <field type="INT64" name="event_threshold" doc="The event threshold." />
> </struct>
>
> <error name="Counter" number="0">
> <field type="CARD32" name="bad_counter" />
> <field type="CARD16" name="minor_opcode" />
> <field type="CARD8" name="major_opcode" />
> + <doc>
> + This error is generated if the value for a COUNTER argument in a
> + request does not name a defined COUNTER.
> + </doc>
> </error>
>
> <error name="Alarm" number="1">
> <field type="CARD32" name="bad_alarm" />
> <field type="CARD16" name="minor_opcode" />
> <field type="CARD8" name="major_opcode" />
> + <doc>
> + This error is generated if the value for an ALARM argument in a
> + request does not name a defined ALARM.
> + </doc>
> </error>
> -
> +
> <request name="Initialize" opcode="0">
> + <doc>
> + <brief>
> + This 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.
> + </brief>
> + <detailed>
> + 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.
> +
> + Given two different versions of the SYNC protocol, v1 and v2, v1
> + is compatible with v2 if and only if @a v1.version_major =
> + @a v2.version_major and @a v1.version\_minor <=
> + @a v2.version_minor. Compatible means that the functionality is
> + fully supported in an identical fashion in the two versions.
> +
> + This document describes major version 3, minor version 0 of the
> + SYNC protocol.
> + </detailed>
> + </doc>
> <reply>
> <pad bytes="1" />
> - <field type="CARD8" name="major_version" />
> - <field type="CARD8" name="minor_version" />
> + <field type="CARD8" name="major_version" doc="major versions of the SYNC protocol" />
> + <field type="CARD8" name="minor_version" doc="minor versions of the SYNC protocol" />
> </reply>
> </request>
>
> <request name="ListSystemCounters" opcode="1">
> + <doc>
> + <brief>
> + This request returns a list of all the system counters that are
> + available at the time the request is executed.
> + </brief>
> + <detailed>
> + 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.
> + </detailed>
> + </doc>
> <reply>
> <pad bytes="1" />
> - <field type="CARD32" name="counters_len" />
> + <field type="CARD32" name="counters_len" doc="The counters count" />
> <pad bytes="20" />
> - <list type="SYSTEMCOUNTER" name="counters">
> + <list type="SYSTEMCOUNTER" name="counters" doc="the list of counters">
> <fieldref>counters_len</fieldref>
> </list>
> </reply>
> + <error code="11" name="Alloc" />
> </request>
>
> <request name="CreateCounter" opcode="2">
> - <field type="COUNTER" name="id" />
> - <field type="INT64" name="initial_value" />
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + 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.
> + </detailed>
> + </doc>
> + <field type="COUNTER" name="id" doc="The id of the counter" />
> + <field type="INT64" name="initial_value" doc="The initial value of the counter" />
> + <error code="11" name="Alloc" />
> + <error code="14" name="IDChoice" />
> </request>
>
> <request name="DestroyCounter" opcode="6">
> - <field type="COUNTER" name="counter" />
> + <doc>
> + <brief>
> + This request destroys the given counter.
> + </brief>
> + <detailed>
> + This request destroys the given counter and sets the counter
> + fields for all triggers that specify this counter to
> + @c None. All clients waiting on the counter are released and a
> + CounterNotify 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 @c Inactive and an
> + AlarmNotify event with a state field of @c Inactive is
> + generated. A counter is destroyed automatically when the
> + connection to the creating client is closed down if the
> + close-down mode is @c Destroy. An Access error is generated if
> + counter is a system counter. A Counter error is generated if
> + counter does not name a valid counter.
> + </detailed>
> + </doc>
> + <field type="COUNTER" name="counter" doc="The counter to destroy" />
> + <error code="0" name="Counter" />
> + <error code="10" name="Access" />
> </request>
>
> <request name="QueryCounter" opcode="5">
> - <field type="COUNTER" name="counter" />
> + <doc>
> + <brief>
> + This request returns the current value of the given counter.
> + </brief>
> + <detailed>
> + This request returns the current value of the given counter or
> + generates a Counter error if counter does not name a valid
> + counter.
> + </detailed>
> + </doc>
> + <field type="COUNTER" name="counter" doc="The counter" />
> <reply>
> <pad bytes="1" />
> - <field type="INT64" name="counter_value" />
> + <field type="INT64" name="counter_value" doc="The value of the counter" />
> </reply>
> + <error code="0" name="Counter" />
> </request>
>
> <request name="Await" opcode="7">
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + </detailed>
> + </doc>
> <list type="WAITCONDITION" name="wait_list" />
> </request>
>
> <request name="ChangeCounter" opcode="4">
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + </detailed>
> + </doc>
> <field type="COUNTER" name="counter" />
> <field type="INT64" name="amount" />
> </request>
>
> <request name="SetCounter" opcode="3">
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + </detailed>
> + </doc>
> <field type="COUNTER" name="counter" />
> <field type="INT64" name="value" />
> </request>
>
> <request name="CreateAlarm" opcode="8">
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + </detailed>
> + </doc>
> <field type="ALARM" name="id" />
> <valueparam value-mask-type="CARD32"
> value-mask-name="value_mask"
> @@ -135,6 +303,12 @@ for licensing information.
> </request>
>
> <request name="ChangeAlarm" opcode="9">
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + </detailed>
> + </doc>
> <field type="ALARM" name="id" />
> <valueparam value-mask-type="CARD32"
> value-mask-name="value_mask"
> @@ -146,6 +320,12 @@ for licensing information.
> </request>
>
> <request name="QueryAlarm" opcode="10">
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + </detailed>
> + </doc>
> <field type="ALARM" name="alarm" />
> <reply>
> <pad bytes="1" />
> @@ -157,11 +337,23 @@ for licensing information.
> </request>
>
> <request name="SetPriority" opcode="12">
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + </detailed>
> + </doc>
> <field type="CARD32" name="id" />
> <field type="INT32" name="priority" />
> </request>
> -
> +
> <request name="GetPriority" opcode="13">
> + <doc>
> + <brief>
> + </brief>
> + <detailed>
> + </detailed>
> + </doc>
> <field type="CARD32" name="id" />
> <reply>
> <pad bytes="1" />
> @@ -170,20 +362,45 @@ for licensing information.
> </request>
>
> <event name="CounterNotify" number="0">
> + <doc>
> + CounterNotify events may be generated when a client becomes
> + unblocked after an Await 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.
> +
> + When a client is unblocked, all the CounterNotify 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 @e n, there
> + are at least @e n more events to follow.
> + </doc>
> <field type="CARD8" name="kind" />
> - <field type="COUNTER" name="counter" />
> - <field type="INT64" name="wait_value" />
> - <field type="INT64" name="counter_value" />
> - <field type="TIMESTAMP" name="timestamp" />
> - <field type="CARD16" name="count" />
> - <field type="BOOL" name="destroyed" />
> + <field type="COUNTER" name="counter" doc="The counter." />
> + <field type="INT64" name="wait_value" doc="The value being waited for." />
> + <field type="INT64" name="counter_value" doc="The actual value of the counter." />
> + <field type="TIMESTAMP" name="timestamp" doc="The server time." />
> + <field type="CARD16" name="count" doc="The events count." />
> + <field type="BOOL" name="destroyed" doc="TRUE if this request was generated as the result of the destruction of the counter and FALSE otherwise." />
> </event>
>
> <event name="AlarmNotify" number="1">
> + <doc>
> + An AlarmNotify 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 @c Inactive, no more events will be generated
> + by this alarm until a ChangeAlarm request is executed, the alarm
> + is destroyed, or the counter for the alarm is destroyed.
> + </doc>
> <field type="CARD8" name="kind" />
> - <field type="ALARM" name="alarm" />
> - <field type="INT64" name="counter_value" />
> - <field type="INT64" name="alarm_value" />
> - <field type="TIMESTAMP" name="timestamp" />
> + <field type="ALARM" name="alarm" doc="The alarm." />
> + <field type="INT64" name="counter_value" doc="The value of the counter." />
> + <field type="INT64" name="alarm_value" doc="The test value of the trigger." />
> + <field type="TIMESTAMP" name="timestamp" doc="The server time." />
> </event>
> </xcb>
>
>
> ------------------------------------------------------------------------
>
> <?xml version="1.0" encoding="utf-8"?>
> <!--
> Copyright (C) 2004 Mikko Torni and Josh Triplett.
> All Rights Reserved. See the file COPYING in this directory
> for licensing information.
> -->
> <xcb header="sync" extension-xname="SYNC" extension-name="Sync"
> major-version="3" minor-version="0">
> <import>xproto</import>
>
> <xidtype name="ALARM" />
>
> <enum name="ALARMSTATE">
> <doc>
> <brief>
> The ALARMSTATE type describe the state of an alarm.
> </brief>
> <detailed>
> The ALARMSTATE type describe the state of an alarm.
> </detailed>
> </doc>
> <item name="Active" doc="The alarm is active." />
> <item name="Inactive" doc="The alarm is inactive." />
> <item name="Destroyed" doc="The alarm is destroyed." />
> </enum>
>
> <xidtype name="COUNTER" />
>
> <enum name="TESTTYPE">
> <item name="PositiveTransition" />
> <item name="NegativeTransition" />
> <item name="PositiveComparison" />
> <item name="NegativeComparison" />
> </enum>
>
> <enum name="VALUETYPE">
> <item name="Absolute" />
> <item name="Relative" />
> </enum>
>
> <enum name="CA">
> <item name="Counter"> <bit>0</bit></item>
> <item name="ValueType"><bit>1</bit></item>
> <item name="Value"> <bit>2</bit></item>
> <item name="TestType"> <bit>3</bit></item>
> <item name="Delta"> <bit>4</bit></item>
> <item name="Events"> <bit>5</bit></item>
> </enum>
>
> <struct name="INT64">
> <field type="INT32" name="hi" />
> <field type="CARD32" name="lo" />
> </struct>
>
> <struct name="SYSTEMCOUNTER">
> <doc>
> <brief>
> The SYSTEMCOUNTER type provides the client with information
> about a System Counter.
> </brief>
> <detailed>
> The SYSTEMCOUNTER type provides the client with information
> about a System 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.
>
> 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.
> </detailed>
> </doc>
> <field type="COUNTER" name="counter" doc="The counter." />
> <field type="INT64" name="resolution" />
> <field type="CARD16" name="name_len" doc="The length of the name of the counter" />
> <list type="CARD8" name="name" doc=" The textual name of the counter" >
> <fieldref>name_len</fieldref>
> </list>
> </struct>
>
> <struct name="TRIGGER">
> <field type="COUNTER" name="counter" />
> <field type="VALUETYPE" name="wait_type" />
> <field type="INT64" name="wait_value" />
> <field type="TESTTYPE" name="test_type" />
> </struct>
>
> <struct name="WAITCONDITION">
> <doc>
> <brief>
> The WAITCONDITION type is simply a trigger with an associated
> event-threshold.
> </brief>
> <detailed>
> The WAITCONDITION type is simply a trigger with an associated
> event-threshold. The event threshold is used by the Await
> 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 Await request was processed after
> the TRIGGER became TRUE, which usually indicates that the server
> is not processing requests as fast as the client expects.
> </detailed>
> </doc>
> <field type="TRIGGER" name="trigger" doc="The trigger." />
> <field type="INT64" name="event_threshold" doc="The event threshold." />
> </struct>
>
> <error name="Counter" number="0">
> <field type="CARD32" name="bad_counter" />
> <field type="CARD16" name="minor_opcode" />
> <field type="CARD8" name="major_opcode" />
> <doc>
> This error is generated if the value for a COUNTER argument in a
> request does not name a defined COUNTER.
> </doc>
> </error>
>
> <error name="Alarm" number="1">
> <field type="CARD32" name="bad_alarm" />
> <field type="CARD16" name="minor_opcode" />
> <field type="CARD8" name="major_opcode" />
> <doc>
> This error is generated if the value for an ALARM argument in a
> request does not name a defined ALARM.
> </doc>
> </error>
>
> <request name="Initialize" opcode="0">
> <doc>
> <brief>
> This 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.
> </brief>
> <detailed>
> 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.
>
> Given two different versions of the SYNC protocol, v1 and v2, v1
> is compatible with v2 if and only if @a v1.version_major =
> @a v2.version_major and @a v1.version\_minor <=
> @a v2.version_minor. Compatible means that the functionality is
> fully supported in an identical fashion in the two versions.
>
> This document describes major version 3, minor version 0 of the
> SYNC protocol.
> </detailed>
> </doc>
> <reply>
> <pad bytes="1" />
> <field type="CARD8" name="major_version" doc="major versions of the SYNC protocol" />
> <field type="CARD8" name="minor_version" doc="minor versions of the SYNC protocol" />
> </reply>
> </request>
>
> <request name="ListSystemCounters" opcode="1">
> <doc>
> <brief>
> This request returns a list of all the system counters that are
> available at the time the request is executed.
> </brief>
> <detailed>
> 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.
> </detailed>
> </doc>
> <reply>
> <pad bytes="1" />
> <field type="CARD32" name="counters_len" doc="The counters count" />
> <pad bytes="20" />
> <list type="SYSTEMCOUNTER" name="counters" doc="the list of counters">
> <fieldref>counters_len</fieldref>
> </list>
> </reply>
> <error code="11" name="Alloc" />
> </request>
>
> <request name="CreateCounter" opcode="2">
> <doc>
> <brief>
> </brief>
> <detailed>
> 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.
> </detailed>
> </doc>
> <field type="COUNTER" name="id" doc="The id of the counter" />
> <field type="INT64" name="initial_value" doc="The initial value of the counter" />
> <error code="11" name="Alloc" />
> <error code="14" name="IDChoice" />
> </request>
>
> <request name="DestroyCounter" opcode="6">
> <doc>
> <brief>
> This request destroys the given counter.
> </brief>
> <detailed>
> This request destroys the given counter and sets the counter
> fields for all triggers that specify this counter to
> @c None. All clients waiting on the counter are released and a
> CounterNotify 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 @c Inactive and an
> AlarmNotify event with a state field of @c Inactive is
> generated. A counter is destroyed automatically when the
> connection to the creating client is closed down if the
> close-down mode is @c Destroy. An Access error is generated if
> counter is a system counter. A Counter error is generated if
> counter does not name a valid counter.
> </detailed>
> </doc>
> <field type="COUNTER" name="counter" doc="The counter to destroy" />
> <error code="0" name="Counter" />
> <error code="10" name="Access" />
> </request>
>
> <request name="QueryCounter" opcode="5">
> <doc>
> <brief>
> This request returns the current value of the given counter.
> </brief>
> <detailed>
> This request returns the current value of the given counter or
> generates a Counter error if counter does not name a valid
> counter.
> </detailed>
> </doc>
> <field type="COUNTER" name="counter" doc="The counter" />
> <reply>
> <pad bytes="1" />
> <field type="INT64" name="counter_value" doc="The value of the counter" />
> </reply>
> <error code="0" name="Counter" />
> </request>
>
> <request name="Await" opcode="7">
> <doc>
> <brief>
> </brief>
> <detailed>
> </detailed>
> </doc>
> <list type="WAITCONDITION" name="wait_list" />
> </request>
>
> <request name="ChangeCounter" opcode="4">
> <doc>
> <brief>
> </brief>
> <detailed>
> </detailed>
> </doc>
> <field type="COUNTER" name="counter" />
> <field type="INT64" name="amount" />
> </request>
>
> <request name="SetCounter" opcode="3">
> <doc>
> <brief>
> </brief>
> <detailed>
> </detailed>
> </doc>
> <field type="COUNTER" name="counter" />
> <field type="INT64" name="value" />
> </request>
>
> <request name="CreateAlarm" opcode="8">
> <doc>
> <brief>
> </brief>
> <detailed>
> </detailed>
> </doc>
> <field type="ALARM" name="id" />
> <valueparam value-mask-type="CARD32"
> value-mask-name="value_mask"
> value-list-name="value_list" />
> </request>
>
> <request name="ChangeAlarm" opcode="9">
> <doc>
> <brief>
> </brief>
> <detailed>
> </detailed>
> </doc>
> <field type="ALARM" name="id" />
> <valueparam value-mask-type="CARD32"
> value-mask-name="value_mask"
> value-list-name="value_list" />
> </request>
>
> <request name="DestroyAlarm" opcode="11">
> <field type="ALARM" name="alarm" />
> </request>
>
> <request name="QueryAlarm" opcode="10">
> <doc>
> <brief>
> </brief>
> <detailed>
> </detailed>
> </doc>
> <field type="ALARM" name="alarm" />
> <reply>
> <pad bytes="1" />
> <field type="TRIGGER" name="trigger" />
> <field type="INT64" name="delta" />
> <field type="BOOL" name="events" />
> <field type="ALARMSTATE" name="state" />
> </reply>
> </request>
>
> <request name="SetPriority" opcode="12">
> <doc>
> <brief>
> </brief>
> <detailed>
> </detailed>
> </doc>
> <field type="CARD32" name="id" />
> <field type="INT32" name="priority" />
> </request>
>
> <request name="GetPriority" opcode="13">
> <doc>
> <brief>
> </brief>
> <detailed>
> </detailed>
> </doc>
> <field type="CARD32" name="id" />
> <reply>
> <pad bytes="1" />
> <field type="INT32" name="priority" />
> </reply>
> </request>
>
> <event name="CounterNotify" number="0">
> <doc>
> CounterNotify events may be generated when a client becomes
> unblocked after an Await 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.
>
> When a client is unblocked, all the CounterNotify 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 @e n, there
> are at least @e n more events to follow.
> </doc>
> <field type="CARD8" name="kind" />
> <field type="COUNTER" name="counter" doc="The counter." />
> <field type="INT64" name="wait_value" doc="The value being waited for." />
> <field type="INT64" name="counter_value" doc="The actual value of the counter." />
> <field type="TIMESTAMP" name="timestamp" doc="The server time." />
> <field type="CARD16" name="count" doc="The events count." />
> <field type="BOOL" name="destroyed" doc="TRUE if this request was generated as the result of the destruction of the counter and FALSE otherwise." />
> </event>
>
> <event name="AlarmNotify" number="1">
> <doc>
> An AlarmNotify 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 @c Inactive, no more events will be generated
> by this alarm until a ChangeAlarm request is executed, the alarm
> is destroyed, or the counter for the alarm is destroyed.
> </doc>
> <field type="CARD8" name="kind" />
> <field type="ALARM" name="alarm" doc="The alarm." />
> <field type="INT64" name="counter_value" doc="The value of the counter." />
> <field type="INT64" name="alarm_value" doc="The test value of the trigger." />
> <field type="TIMESTAMP" name="timestamp" doc="The server time." />
> </event>
> </xcb>
>
>
> ------------------------------------------------------------------------
>
> % $Xorg: sync.tex,v 1.3 2000/08/17 19:42:37 cpqbld Exp $
> % $XdotOrg: xc/doc/specs/Xext/sync.tex,v 1.2 2004/04/23 18:42:18 eich Exp $
> %
> % Copyright 1991 by Olivetti Research Limited, Cambridge, England and
> % Digital Equipment Corporation, Maynard, Massachusetts.
> %
> % All Rights Reserved
> %
> % Permission to use, copy, modify, and distribute this software and its
> % documentation for any purpose and without fee is hereby granted,
> % provided that the above copyright notice appear in all copies and that
> % both that copyright notice and this permission notice appear in
> % supporting documentation, and that the names of Digital or Olivetti
> % not be used in advertising or publicity pertaining to distribution of the
> % software without specific, written prior permission.
> %
> % DIGITAL AND OLIVETTI DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
> % INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT
> % SHALL THEY BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
> % ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
> % IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
> % OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
> %
> % $XFree86$
>
> %\documentstyle[a4]{article}
> \documentstyle{article}
>
> \setlength{\parindent}{0 pt}
> \setlength{\parskip}{6pt}
>
> % Protocol Section
> % For the DP book, these four should be assigned the font for global symbols.
>
> \newcommand{\request}[1]{{\bf #1}}
> \newcommand{\event}[1]{{\bf #1}}
> \newcommand{\error}[1]{{\bf #1}}
> \newcommand{\enum}[1]{{\bf #1}}
>
> % The following fonts are not reassigned for the DP book.
>
> \newcommand{\system}[1]{{\sc #1}}
> \newcommand{\param}[1]{{\it #1}}
>
> \newcommand{\eventdef}[1]{\item {\bf#1}}
> \newcommand{\requestdef}[1]{\item {\bf#1}}
> \newcommand{\errordef}[1]{\item {\bf#1}}
>
> \newcommand{\defn}[1]{{\bf #1}}
>
> \newcommand{\tabstopsA}{\hspace*{4cm}\=\hspace*{1cm}\=\hspace*{7cm}\=\kill}
> \newcommand{\tabstopsB}{\hspace*{1cm}\=\hspace*{1cm}\=\hspace*{3cm}\=\kill}
> \newcommand{\tabstopsC}{\hspace*{1cm}\=\hspace*{1cm}\=\hspace*{5cm}\=\kill}
>
> % commands for formatting the API
> % For the DP book, these three should be assigned the font for global symbols.
>
> \newcommand{\cfunctionname}[1]{\mbox{\tt#1}}
> \newcommand{\ctypename}[1]{\mbox{\tt#1}}
> \newcommand{\cconst}[1]{\mbox{\tt#1}}
>
> % For the DP book, within function definitions, the type and name are in
> % the ordinary font; therefore, ctypenamedef and cfunctionnamedef are used
> % and defined below.
> \newcommand{\ctypenamedef}[1]{\mbox{#1}}
> \newcommand{\cfunctionnamedef}[1]{\mbox{#1}}
> \newcommand{\cargname}[1]{\mbox{\it#1}}
> \newcommand{\cstartfunction}[2]{\begin{sloppypar}\begin{samepage}\ctypenamedef{#1}\\ \cfunctionnamedef{#2}\ (}
> \newcommand{\cargdecl}[2]{\penalty -1\ctypenamedef{#1} \cargname{#2}}
> \newcommand{\cendfunctiondecl}{){\hangafter=2 \hangindent=20pt \raggedright\par}}
> \newcommand{\cendfuncdescription}{\end{samepage}\end{sloppypar}}
>
> \newcommand{\cstartmacro}[2]{\begin{sloppypar}\begin{samepage}\ctypenamedef{#1}\\ \cfunctionnamedef{#2}\ (}
> \newcommand{\cendmacrodecl}{)\par}
> \newcommand{\cendmacrodescription}{\end{samepage}\end{sloppypar}}
>
> % make things easier with all the long names
> \spaceskip .3333em plus 5em
> \tolerance=2000
>
> \begin{document}
>
> \begin{center}
>
> {\large X Synchronization Extension Protocol}\\[10pt]
> {\large Version 3.0}\\[15pt]
> {\large X Consortium Standard}\\[15pt]
> {\large X Version 11, Release 6.8}\\[15pt]
> {\it Tim Glauert}\\[0pt]
> {\tt thg at cam-orl.co.uk}\\[0pt]
> {\bf Olivetti Research / MultiWorks}\\[5pt]
> {\it Dave Carver}\\[0pt]
> {\tt dcc at athena.mit.edu}\\[0pt]
> {\bf Digital Equipment Corporation,}\\[0pt]
> {\bf MIT / Project Athena}\\[5pt]
> {\it Jim Gettys}\\[0pt]
> {\tt jg at crl.dec.com}\\[0pt]
> {\bf Digital Equipment Corporation,}\\[0pt]
> {\bf Cambridge Research Laboratory}\\[5pt]
> {\it David P. Wiggins}\\[0pt]
> {\tt dpw at x.org}\\[0pt]
> {\bf X Consortium, Inc.}\\[0pt]
>
> \end {center}
>
> Copyright 1991 by Olivetti Research Limited, Cambridge, England and
> Digital Equipment Corporation, Maynard, Massachusetts.
>
> {\small 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.}
>
> Copyright (c) 1991 X Consortium, Inc.
>
> {\small 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:
>
> The above copyright notice and this permission notice shall be included in
> all copies or substantial portions of the Software.
>
> 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.
>
> 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.}
> \eject
>
> \section{Synchronization Protocol}
>
> 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.
>
> 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.
>
> 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.
>
> \subsection{Description}
>
> 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.
>
> The extension adds \defn{Counter} and \defn{Alarm} 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 \request{Await} request that waits until
> one of a set of synchronization conditions, called TRIGGERs, becomes TRUE.
>
> The \request{CreateCounter} request allows a client to create a
> \defn{Counter} that can be changed by explicit \request{SetCounter} and
> \request{ChangeCounter} requests. These can be used to implement
> synchronization between different clients.
>
> There are some counters, called \defn{System Counters}, 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.
>
> The extension provides an \defn{Alarm} mechanism that allows clients to
> receive an event on a regular basis when a particular counter is changed.
>
> \subsection{Types}
>
> Please refer to the X11 Protocol specification as this document uses
> syntactic conventions established there and references types defined there.
>
> The following new types are used by the extension.
>
> \begin{tabbing}{l}
> SYSTEMCOUNTER: \=\kill
> INT64: \>64-bit signed integer\\
> COUNTER:\>XID\\
> VALUETYPE:\> \{\enum{Absolute},\enum{Relative}\}\\
> TESTTYPE:\> \{\enum{PositiveTransition},\enum{NegativeTransition},\\
> \>\enum{PositiveComparison},\enum{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:\> \{\enum{Active},\enum{Inactive},\enum{Destroyed}\}\\
> \end{tabbing}
>
> The COUNTER type defines the client-side handle on a server \defn{Counter}.
> The value of a counter is an INT64.
>
> 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.
>
> 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 \error{Value} error. If the
> value-type field is \enum{Absolute}, the test value is given by the
> wait-value field. If the value-type field is
> \enum{Relative}, 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
> \error{Value} error. If counter is \enum{None} and the
> value-type is \enum{Relative}, the request that initialized the
> trigger will return a \error{Match} error.
> If counter is not \enum{None} and does not name a valid
> counter, a \error{Counter} error is generated.
>
> If the test-type is \enum{PositiveTransition}, 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 \enum{NegativeTransition}, 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
> \enum{PositiveComparison}, the trigger is TRUE if the counter is greater than or
> equal to the test value and FALSE otherwise. If the test-type is
> \enum{NegativeComparison}, 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 \error{Value} error. A trigger
> with a counter value of \enum{None} and a valid test-type
> is always TRUE.
>
> The WAITCONDITION type is simply a trigger with an associated
> event-threshold. The event threshold is used by the \request{Await}
> 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
> \request{Await} request was processed after the TRIGGER became TRUE,
> which usually indicates that the server is not processing requests as fast as
> the client expects.
>
> The SYSTEMCOUNTER type provides the client with information about a
> \defn{System 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.
>
> The only system counter that is guaranteed to be present is called
> \system{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.
>
> An ALARM is the client-side handle on an \defn{Alarm} resource.
>
> \subsection{Errors}
>
> \begin{description}
>
> \errordef{Counter}
>
> This error is generated if the value for a COUNTER argument in a request does
> not name a defined COUNTER.
>
> \errordef{Alarm}
>
> This error is generated if the value for an ALARM argument in a request does
> not name a defined ALARM.
>
> \end{description}
>
> \subsection{Requests}
>
> \begin{description}
>
> % start marker
> \requestdef{Initialize}
>
> \begin{tabular}{l}
> \param{version-major},\param{version-minor}: CARD8
> \end{tabular}\\
> $\Rightarrow$\\
> \begin{tabular}{l}
> version-major,version-minor: CARD8
> \end{tabular}
> %end marker
>
> 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.
>
> 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 \leq v2.version\_minor$. Compatible means that the
> functionality is fully supported in an identical fashion in the two
> versions.
>
> This document describes major version 3, minor version 0 of the SYNC
> protocol.
>
> % start marker
> \requestdef{ListSystemCounters}
>
> $\Rightarrow$\\
> \begin{tabular}{l}
> system-counters: LISTofSYSTEMCOUNTER\\[5pt]
> Errors: \error{Alloc}
> \end{tabular}
> % end marker
>
> 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.
>
> % start marker
> \requestdef{CreateCounter}
>
> \begin{tabular}{l}
> \param{id}: COUNTER\\
> \param{initial-value}: INT64\\[5pt]
> Errors: \error{IDChoice},\error{Alloc}
> \end{tabular}
> % end marker
>
> 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.
>
> % start marker
> \requestdef{DestroyCounter}
>
> \begin{tabular}{l}
> \param{counter}: COUNTER\\[5pt]
> Errors: \error{Counter},\error{Access}
> \end{tabular}
> % end marker
>
> This request destroys the given counter and sets the counter fields
> for all triggers that specify this counter to \enum{None}. All clients
> waiting on the counter are released and a \event{CounterNotify} 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 \enum{Inactive} and an \event{AlarmNotify} event with a state
> field of \enum{Inactive} is generated. A counter is destroyed automatically
> when the connection to the creating client is closed down if the close-down
> mode is {\bf Destroy}. An \error{Access} error is generated if counter
> is a system counter. A \error{Counter} error is generated if counter
> does not name a valid counter.
>
> % start marker
> \requestdef{QueryCounter}
>
> \begin{tabular}{l}
> \param{counter}: COUNTER\\
> \end{tabular}\\
> $\Rightarrow$\\
> \begin{tabular}{l}
> value: INT64\\[5pt]
> Errors: \error{Counter}
> \end{tabular}
> % end marker
>
> This request returns the current value of the given counter or a generates
> \error{Counter} error if counter does not name a valid counter.
>
> % start marker
> \requestdef{Await}
>
> \begin{tabular}{l}
> \param{wait-list}: LISTofWAITCONDITION\\[5pt]
> Errors: \error{Counter},\error{Alloc},\error{Value}
> \end{tabular}
> % end marker
>
> 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 \request{SetCounter},
> \request{ChangeCounter} or \request{DestroyCounter} request.
>
> A \error{Value} error is generated if wait-list is empty.
>
> When the client becomes unblocked, each trigger is checked to determine
> whether a \event{CounterNotify} 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 \enum{PositiveTransition} or \enum{PositiveComparison}, a \event{CounterNotify} event is generated if the
> difference is at least event-threshold. If the test-type is
> \enum{NegativeTransition} or \enum{NegativeComparison}, a
> \event{CounterNotify} 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.
>
> This threshold check is made for each trigger in the list and a
> \event{CounterNotify} event is generated for every trigger for which
> the check succeeds. The check for \enum{CounterNotify} events is performed
> even if one of the triggers is TRUE when the request is first executed. Note
> that a \event{CounterNotify} event may be generated for a trigger that
> is FALSE if there are multiple triggers in the request. A
> \event{CounterNotify} event with the destroyed flag set to TRUE is
> always generated if the counter for one of the triggers is destroyed.
>
> % start marker
> \requestdef{ChangeCounter}
>
> \begin{tabular}{l}
> \param{counter}: COUNTER\\
> \param{amount}: INT64\\[5pt]
> Errors: \error{Counter},\error{Access},\error{Value}
> \end{tabular}
> % end marker
>
> 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
> \event{CounterNotify} events may be generated. If the change to the counter
> satisfies the trigger for an alarm, an \event{AlarmNotify} event is generated
> and the alarm is updated. An \error{Access} error is generated if
> counter is a system counter. A \error{Counter} 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 \error{Value} error is
> generated and the counter is not changed.
>
> 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.
>
> % start marker
> \requestdef{SetCounter}
>
> \begin{tabular}{l}
> \param{counter}: COUNTER\\
> \param{value}: INT64\\[5pt]
> Errors: \error{Counter},\error{Access}
> \end{tabular}
> % end marker
>
> This request sets the value of the given counter to value. The effect
> is equivalent to executing the appropriate \request{ChangeCounter} request to
> change the counter value to value. An \error{Access} error is
> generated if counter names a system counter. A \error{Counter} error
> is generated if counter does not name a valid counter.
>
> % start marker
> \requestdef{CreateAlarm}
>
> \begin{tabular}{l}
> \param{id}: ALARM\\
> \param{values-mask}: CARD32\\
> \param{values-list}: LISTofVALUE\\[5pt]
> Errors: \error{IDChoice},\error{Counter},\error{Match},\error{Value},\error{Alloc}
> \end{tabular}
> % end marker
>
> 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:
>
> \begin{center}
> \begin{tabular}{l|l|ll}
> Attribute & Type & Default \\
> \hline
> trigger & TRIGGER & counter & \enum{None}\\
> & & value-type & \enum{Absolute}\\
> & & value & 0\\
> & & test-type & \enum{PositiveComparison}\\
> delta & INT64 & 1 \\
> events & BOOL & TRUE
> \end{tabular}
> \end{center}
>
> The trigger is initialized as described in the definition of TRIGGER,
> with an error being generated if necessary.
>
> If the counter is \enum{None}, the state of the alarm is set to
> \enum{Inactive}, else it is set to \enum{Active}.
>
> Whenever the trigger becomes TRUE, either as a result of this request
> or as the result of a \request{SetCounter}, \request{ChangeCounter},
> \request{DestroyCounter}, or \request{ChangeAlarm} request, an
> \event{AlarmNotify} 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 \enum{None}, or if the
> delta is 0 and test-type is \enum{PositiveComparison} or
> \enum{NegativeComparison}, no change is made to value and the alarm
> state is changed to \enum{Inactive} before the event is generated. No further
> events are generated by an \enum{Inactive} alarm until a \request{ChangeAlarm}
> or \request{DestroyAlarm} request is executed.
>
> If the test-type is \enum{PositiveComparison} or
> \enum{PositiveTransition} and delta is less than zero, or
> if the test-type is \enum{NegativeComparison} or
> \enum{NegativeTransition} and delta is greater than zero,
> a \error{Match} error is generated.
>
> The events value enables or disables delivery of \event{AlarmNotify}
> 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.
>
> An \event{AlarmNotify} event is always generated at some time after the
> execution of a \request{CreateAlarm} 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.
>
> % start marker
> \requestdef{ChangeAlarm}
>
> \begin{tabular}{l}
> \param{id}: ALARM\\
> \param{values-mask}: CARD32\\
> \param{values-list}: LISTofVALUE\\[5pt]
> Errors: \error{Alarm},\error{Counter},\error{Value},\error{Match}
> \end{tabular}
> % end marker
>
> This request changes the parameters of an Alarm. All of the parameters
> specified for the \request{CreateAlarm} request may be changed using this
> request. The trigger is reinitialized and an \event{AlarmNotify}
> event is generated if appropriate, as explained in the description of the
> \request{CreateAlarm} request.
>
> 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.
>
> 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.
>
> % start marker
> \requestdef{DestroyAlarm}
>
> \begin{tabular}{l}
> \param{alarm}: ALARM\\[5pt] Errors: \error{Alarm}
> \end{tabular}
> % end marker
>
> This request destroys an alarm. An alarm is automatically destroyed
> when the creating client is closed down if the close-down mode is {\bf
> Destroy}. When an alarm is destroyed, an \event{AlarmNotify} event is
> generated with a state value of \enum{Destroyed}.
>
> % start marker
> \requestdef{QueryAlarm}
>
> \begin{tabular}{l}
> \param{alarm}: ALARM\\
> \end{tabular}\\
> $\Rightarrow$\\
> \begin{tabular}{l}
> trigger: TRIGGER\\
> delta: INT64\\
> events: ALARMEVENTMASK\\
> state: ALARMSTATE\\[5pt]
> Errors: \error{Alarm}
> \end{tabular}
> % end marker
>
> This request retrieves the current parameters for an Alarm.
>
> % start marker
> \requestdef{SetPriority}
>
> \begin{tabular}{l}
> \param{client-resource}: XID\\
> \param{priority}: INT32\\[5pt]
> Errors: \error{Match}
> \end{tabular}
> % end marker
>
> This request changes the scheduling priority of the client that created
> client-resource. If client-resource is \enum{None}, then the
> priority for the client making the request is changed. A \error{Match} error
> is generated if client-resource is not \enum{None} and does not name
> an existing resource in the server. For any two priority values,
> {\tt A} and {\tt B}, {\tt A} is higher priority if and only if {\tt A} is
> greater than {\tt B}.
>
> The priority of a client is set to 0 when the initial client connection is
> made.
>
> 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.
>
> 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.
>
> % start marker
> \requestdef{GetPriority}
>
> \begin{tabular}{l}
> \param{client-resource}: XID\\
> \end{tabular}\\
> $\Rightarrow$\\
> \begin{tabular}{l}
> priority: INT32\\[5pt]
> Errors: \error{Match}
> \end{tabular}
> % end marker
>
> This request returns the scheduling priority of the client that created
> client-resource. If client-resource is \enum{None}, then the
> priority for the client making the request is returned. A \error{Match} error
> is generated if client-resource is not \enum{None} and does not name
> an existing resource in the server.
>
> \end{description}
>
> \subsection{Events}
>
> \begin{description}
>
> % start marker
> \eventdef{CounterNotify}
>
> \begin{tabular}{l}
> \param{counter}: COUNTER \\
> \param{wait-value}: INT64 \\
> \param{counter-value}: INT64 \\
> \param{time}: TIME \\
> \param{count}: CARD16 \\
> \param{destroyed}: BOOL
> \end{tabular}
> % end marker
>
> \event{CounterNotify} events may be generated when a client becomes unblocked
> after an \request{Await} 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.
>
> When a client is unblocked, all the \event{CounterNotify} events for the
> \request{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.
>
> % start marker
> \eventdef{AlarmNotify}
>
> \begin{tabular}{l}
> \param{alarm}: ALARM \\
> \param{counter-value}: INT64 \\
> \param{alarm-value}: INT64 \\
> \param{state}: ALARMSTATE \\
> \param{time}: TIME
> \end{tabular}
> % end marker
>
> An \event{AlarmNotify} 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
> \enum{Inactive}, no more events will be generated by this alarm until a
> \request{ChangeAlarm} request is executed, the alarm is destroyed, or the
> counter for the alarm is destroyed.
>
> \end{description}
>
> \section{Encoding}
>
> Please refer to the X11 Protocol Encoding document as this section uses
> syntactic conventions established there and references types defined there.
>
> The name of this extension is ``SYNC''.
>
> \subsection{New Types}
>
> The following new types are used by the extension.
>
> \begin{tabbing}
> \tabstopsC
> ALARM: CARD32\\
> ALARMSTATE:\\
> \tabstopsB
> \> 0 \> Active \\
> \> 1 \> Inactive \\
> \> 2 \> Destroyed\\
> \tabstopsC
> 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:\\
> \tabstopsB
> \> 0 \> PositiveTransition \\
> \> 1 \> NegativeTransition \\
> \> 2 \> PositiveComparison \\
> \> 3 \> NegativeComparison \\
> \tabstopsC
> TRIGGER:\\
> \> 4 \> COUNTER \> counter \\
> \> 4 \> VALUETYPE \> wait-type \\
> \> 8 \> INT64 \> wait-value \\
> \> 4 \> TESTTYPE \> test-type \\
> VALUETYPE:\\
> \tabstopsB
> \> 0 \> Absolute \\
> \> 1 \> Relative \\
> \tabstopsC
> WAITCONDITION:\\
> \> 20 \> TRIGGER \> trigger \\
> \> 8 \> INT64 \> event threshold\\
> \end{tabbing}
>
> 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.
>
> \subsection{Errors}
>
> \begin{tabbing}
> \tabstopsC
> {\bf Counter}\\
> \> 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 \\
> {\bf Alarm}\\
> \> 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 \\
> \end{tabbing}
>
> \subsection{Requests}
>
> \renewcommand{\thefootnote}{\fnsymbol{footnote}}
> \setcounter{footnote}{1}
> \setlength{\topsep}{0pt} %vertical space before and after tabbing
> \begin{tabbing}
> \tabstopsC
> {\bf Initialize}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 0 \> minor opcode \\
> \> 2 \> 2 \> request length \\
> \> 1 \> CARD8 \> major version \\
> \> 1 \> CARD8 \> minor version \\
> \> 2 \> \> unused \\
> $\Rightarrow$\\
> \> 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 \\
> \\
> {\bf ListSystemCounters}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 1 \> minor opcode \\
> \> 2 \> 1 \> request length \\
> $\Rightarrow$\\
> \> 1 \> 1 \> Reply \\
> \> 1 \> \> unused \\
> \> 2 \> CARD16 \> sequence number \\
> \> 4 \> {\it variable} \> reply length \\
> \> 4 \> INT32 \> list length \\
> \> 20 \> \> unused \\
> \> 4n \> list of SYSTEMCOUNTER \> system counters \\
> \\
> {\bf CreateCounter}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 2 \> minor opcode \\
> \> 2 \> 4 \> request length \\
> \> 4 \> COUNTER \> id\\
> \> 8 \> INT64 \> initial value\\
> \\
> {\bf DestroyCounter}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 6 \> minor opcode\footnotemark[1] \\
> \> 2 \> 2 \> request length \\
> \> 4 \> COUNTER \> counter
> \end{tabbing}
> \footnotetext{A previous version of this document gave an incorrect
> minor opcode.}
> \begin{tabbing}
> \tabstopsC
> {\bf QueryCounter}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 5 \> minor opcode\footnotemark[1] \\
> \> 2 \> 2 \> request length \\
> \> 4 \> COUNTER \> counter \\
> $\Rightarrow$\\
> \> 1 \> 1 \> Reply \\
> \> 1 \> \> unused \\
> \> 2 \> CARD16 \> sequence number \\
> \> 4 \> 0 \> reply length \\
> \> 8 \> INT64 \> counter value \\
> \> 16 \> \> unused\\
> \\
> {\bf Await}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 7 \> minor opcode\footnotemark[1] \\
> \> 2 \> 1 + 7*n \> request length \\
> \> 28n \> LISTofWAITCONDITION \> wait conditions
> \end{tabbing}
> \footnotetext{A previous version of this document gave an incorrect
> minor opcode.}
> \setlength{\topsep}{0pt} %vertical space before and after tabbing
> \begin{tabbing}
> \tabstopsC
> {\bf ChangeCounter}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 4 \> minor opcode\footnotemark[1] \\
> \> 2 \> 4 \> request length \\
> \> 4 \> COUNTER \> counter \\
> \> 8 \> INT64 \> amount \\
> \\
> {\bf SetCounter}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 3 \> minor opcode\footnotemark[1] \\
> \> 2 \> 4 \> request length \\
> \> 4 \> COUNTER \> counter \\
> \> 8 \> INT64 \> value \\
> \\
> {\bf CreateAlarm}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 8 \> minor opcode \\
> \> 2 \> 3+n \> request length \\
> \> 4 \> ALARM \> id \\
> \> 4 \> BITMASK \> values mask\\
> \tabstopsB
> \> \> \#x00000001 \> counter \\
> \> \> \#x00000002 \> value-type \\
> \> \> \#x00000004 \> value \\
> \> \> \#x00000008 \> test-type \\
> \> \> \#x00000010 \> delta \\
> \> \> \#x00000020 \> events \\
> \tabstopsC
> \> 4n \> LISTofVALUE \> values\\
> \tabstopsB
> VALUES\\
> \> 4 \> COUNTER \> counter\\
> \> 4 \> VALUETYPE \> value-type \\
> \> 8 \> INT64 \> value \\
> \> 4 \> TESTTYPE \> test-type \\
> \> 8 \> INT64 \> delta \\
> \> 4 \> BOOL \> events\\
> \tabstopsC
> \\
> {\bf ChangeAlarm}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 9 \> minor opcode \\
> \> 2 \> 3+n \> request length \\
> \> 4 \> ALARM \> id \\
> \> 4 \> BITMASK \> values mask \\
> \> \> encodings as for {\bf CreateAlarm}\\
> \> 4n \> LISTofVALUE \> values\\
> \> \> encodings as for {\bf CreateAlarm}\\
> \\
> {\bf DestroyAlarm}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 11 \> minor opcode\footnotemark[1] \\
> \> 2 \> 2 \> request length \\
> \> 4 \> ALARM \> alarm
> \end{tabbing}
> \footnotetext{A previous version of this document gave an incorrect
> minor opcode.}
> \begin{tabbing}
> \tabstopsC
> {\bf QueryAlarm}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 10 \> minor opcode\footnotemark[1] \\
> \> 2 \> 2 \> request length \\
> \> 4 \> ALARM \> alarm \\
> $\Rightarrow$\\
> \> 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 \\
> \\
> {\bf SetPriority}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 12 \> minor opcode \\
> \> 2 \> 3 \> request length \\
> \> 4 \> CARD32 \> id \\
> \> 4 \> INT32 \> priority \\
> \\
> {\bf GetPriority}\\
> \> 1 \> CARD8 \> major opcode \\
> \> 1 \> 13 \> minor opcode \\
> \> 2 \> 1 \> request length \\
> \> 4 \> CARD32 \> id \\
> $\Rightarrow$\\
> \> 1 \> 1 \> Reply \\
> \> 1 \> \> unused \\
> \> 2 \> CARD16 \> sequence number \\
> \> 4 \> 0 \> reply length \\
> \> 4 \> INT32 \> priority \\
> \> 20 \> \> unused\\
> \end{tabbing}
>
> \subsection{Events}
>
> \begin{tabbing}
> \tabstopsC
> {\bf CounterNotify}\\
> \> 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 \\
> \\
> {\bf AlarmNotify}\\
> \> 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\\
> \end{tabbing}
> \end{document}
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb
More information about the Xcb
mailing list