1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" 4[ 5<!ENTITY % defs SYSTEM "defs.ent"> %defs; 6]> 7 8<!--translated from sync.tex, on 2010-06-29 10:52:00, 9by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,refcaption --> 10 11 12<book id="sync"> 13 14<bookinfo> 15 <title>X Synchronization Extension Protocol</title> 16 <subtitle>X Consortium Standard</subtitle> 17 <authorgroup> 18 <author> 19 <firstname>Tim</firstname><surname>Glauert</surname> 20 <affiliation> 21 <orgname>Olivetti Research</orgname> 22 <orgdiv>MultiWorks</orgdiv> 23 </affiliation> 24 </author> 25 <othercredit> 26 <firstname>Dave</firstname> 27 <surname>Carver</surname> 28 <affiliation> 29 <orgname>Digital Equipment Corporation</orgname> 30 <orgdiv>MIT/Project Athena</orgdiv> 31 </affiliation> 32 </othercredit> 33 <othercredit> 34 <firstname>Jim</firstname> 35 <surname>Gettys</surname> 36 <affiliation> 37 <orgname>Digital Equipment Corporation</orgname> 38 <orgdiv>Cambridge Research Laboratory</orgdiv> 39 </affiliation> 40 </othercredit> 41 <othercredit> 42 <firstname>David</firstname> 43 <othername>P.</othername> 44 <surname>Wiggins</surname> 45 <affiliation><orgname>X Consortium, Inc.</orgname></affiliation> 46 </othercredit> 47 <othercredit> 48 <firstname>James</firstname> 49 <surname>Jones</surname> 50 <affiliation><orgname>NVIDIA Corporation</orgname></affiliation> 51 </othercredit> 52 </authorgroup> 53 <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> 54 <releaseinfo>Version 3.1</releaseinfo> 55 <copyright><year>1991</year> 56 <holder>Olivetti Research Limited, Cambridge England</holder> 57 <holder>Digital Equipment Corporation, Maynard, Massachusetts</holder> 58 <holder>X Consortium</holder> 59 </copyright> 60 <copyright><year>2010</year><holder>NVIDIA Corporation</holder></copyright> 61 62<legalnotice> 63<para> 64Permission to use, copy, modify, and distribute this documentation for any 65purpose and without fee is hereby granted, provided that the above 66copyright notice appear in all copies. Olivetti, Digital, MIT, the 67X Consortium, and NVIDIA make no representations about the suitability for 68any purpose of the information in this document. This documentation is 69provided as is without express or implied warranty. 70</para> 71 72<para> 73Permission is hereby granted, free of charge, to any person obtaining 74a copy of this software and associated documentation files 75(the "Software"), to deal in the Software without 76restriction, including without limitation the rights to use, copy, 77modify, merge, publish, distribute, sublicense, and/or sell copies of 78the Software, and to permit persons to whom the Software is furnished 79to do so, subject to the following conditions: 80</para> 81 82<para>The above copyright notice and this permission notice shall be included 83in all copies or substantial portions of the Software.</para> 84 85<para>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY 86KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 87MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO 88EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 89LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 90OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 91SOFTWARE.</para> 92 93<para>Except as contained in this notice, the name of the X Consortium shall 94not be used in advertising or otherwise to promote the sale, use or other 95dealings in this Software without prior written authorization from the X 96Consortium.</para> 97</legalnotice> 98 99</bookinfo> 100 101<chapter id='Synchronization_Protocol'> 102<title>Synchronization Protocol</title> 103<para> 104The core X protocol makes no guarantees about the relative order of execution 105of requests for different clients. This means that any synchronization between 106clients must be done at the client level in an operating system-dependent and 107network-dependent manner. Even if there was an accepted standard for such 108synchronization, the use of a network introduces unpredictable delays between 109the synchronization of the clients and the delivery of the resulting requests 110to the X server. 111</para> 112 113<para> 114The core X protocol also makes no guarantees about the time at which requests 115are executed, which means that all clients with real-time constraints must 116implement their timing on the host computer. Any such timings are subject to 117error introduced by delays within the operating system and network and are 118inefficient because of the need for round-trip requests that keep the client 119and server synchronized. 120</para> 121 122<para> 123The synchronization extension provides primitives that allow synchronization 124between clients to take place entirely within the X server. This removes any 125error introduced by the network and makes it possible to synchronize clients 126on different hosts running different operating systems. This is important for 127multimedia applications, where audio, video, and graphics data streams are 128being synchronized. The extension also provides internal timers within the 129X server to which client requests can be synchronized. This allows simple 130animation applications to be implemented without any round-trip requests and 131makes best use of buffering within the client, network, and server. 132</para> 133 134<sect1 id='Description'> 135<title>Description</title> 136<para> 137The mechanism used by this extension for synchronization within the X 138server is to block the processing of requests from a client until a 139specific synchronization condition occurs. When the condition occurs, the 140client is released and processing of requests continues. Multiple clients 141may block on the same condition to give inter-client synchronization. 142Alternatively, a single client may block on a condition such as an animation 143frame marker. 144</para> 145 146<para> 147The extension adds <function>Counter</function>, <function>Alarm</function>, 148and <function>Fence</function> to the set of resources managed by the 149server. A counter has a 64-bit integer value that may be increased or 150decreased by client requests or by the server internally. A client can block 151by sending an Await request that waits until one of a set of synchronization 152conditions, called TRIGGERs, becomes TRUE. Alarms generate events when 153counter values go through a specified transition. A fence has two possible 154states: triggered and not triggered. Client requests can put the fence in 155either of these states. A client can block until one of a set of fences 156becomes triggered by sending an AwaitFence request. Fences are bound to a 157particular screen at creation time. 158</para> 159 160<para> 161The <function>CreateCounter</function> request allows a client to create a 162<function>Counter</function> that can be changed by explicit 163<function>SetCounter</function> and <function>ChangeCounter</function> 164requests. These can be used to implement synchronization between different 165clients. 166</para> 167 168<para> 169There are some counters, called <function>System Counters</function>, that 170are changed by the server internally rather than by client requests. The 171effect of any change to a system counter is not visible until the server 172has finished processing the current request. In other words, system 173counters are apparently updated in the gaps between the execution of 174requests rather than during the actual execution of a request. The extension 175provides a system counter that advances with the server time as defined by 176the core protocol, and it may also provide counters that advance with the 177real-world time or that change each time the CRT screen is refreshed. 178Other extensions may provide their own extension-specific system counters. 179</para> 180 181<para> 182The extension provides an <function>Alarm</function> mechanism that allows 183clients to receive an event on a regular basis when a particular counter 184is changed. 185</para> 186 187<para> 188The <function>CreateFence</function> request allows a client to create a 189<function>Fence</function> that can be triggered and reset using 190<function>TriggerFence</function> and <function>ResetFence</function> 191requests, respectively. <function>CreateFence</function> takes a drawable 192argument that implies which screen the fence should be created on. The 193<function>TriggerFence</function> request changes the fence's state only 194after all previous rendering commands affecting objects owned by the given 195fence's screen have completed. Note that while fence objects are bound 196to a screen and the simple trigger operation provided by this extension 197operates at screen granularity, other extensions may add more fine-grained 198trigger operations based on any number of events. The screen binding 199merely establishes an upper bound for the scope of fence operations. 200</para> 201 202</sect1> 203<sect1 id='Types'> 204<title>Types</title> 205<para> 206Please refer to the X11 Protocol specification as this document uses 207syntactic conventions established there and references types defined there. 208</para> 209 210<para>The following new types are used by the extension.</para> 211 212<literallayout class="monospaced"> 213INT64: 64-bit signed integer 214COUNTER: XID 215VALUETYPE: {Absolute,Relative}; 216TESTTYPE: {PositiveTransition,NegativeTransition, 217 PositiveComparison,NegativeComparison} 218TRIGGER: [ 219 counter:COUNTER, 220 value-type:VALUETYPE, 221 wait-value:INT64, 222 test-type:TESTTYPE 223 ] 224WAITCONDITION: [ 225 trigger:TRIGGER, 226 event-threshold:INT64 227 ] 228SYSTEMCOUNTER: [ 229 name:STRING8, 230 counter:COUNTER, 231 resolution:INT64 232 ] 233ALARM: XID 234ALARMSTATE: {Active,Inactive,Destroyed} 235FENCE: XID 236</literallayout> 237 238<para> 239The COUNTER type defines the client-side handle on a server 240<function>Counter</function>. The value of a counter is an INT64. 241</para> 242 243<para> 244The TRIGGER type defines a test on a counter that is either TRUE or FALSE. The 245value of the test is determined by the combination of a test value, the value 246of the counter, and the specified test-type. 247</para> 248 249<para> 250The test value for a trigger is calculated using the value-type and 251wait-value fields when the trigger is initialized. If the value-type field 252is not one of the named VALUETYPE constants, the request that initialized the 253trigger will return a <function>Value</function> error. If the value-type 254field is <function>Absolute</function>, the test value is given by the 255wait-value field. If the value-type field is <function>Relative</function>, 256the test value is obtained by adding the wait-value field to the value of the 257counter. If the resulting test value would lie outside the range for an 258INT64, the request that initialized the trigger will return a 259<function>Value</function> error. If counter is <function>None</function> 260and the value-type is <function>Relative</function>, the request that 261initialized the trigger will return a <function>Match</function> error. If 262counter is not None and does not name a valid counter, a Counter error is 263generated. 264</para> 265 266<para> 267If the test-type is <function>PositiveTransition</function>, the trigger is 268initialized to FALSE, and it will become TRUE when the counter changes from 269a value less than the test value to a value greater than or equal to the 270test value. If the test-type is <function>NegativeTransition</function>, 271the trigger is initialize to FALSE, and it will become TRUE when the counter 272changes from a value greater than the test value to a value less than or 273equal to the test value. If the test-type is 274<function>PositiveComparison</function>, the trigger is TRUE if the 275counter is greater than or equal to the test value and FALSE otherwise. If the 276test-type is <function>NegativeComparison</function>, the trigger is TRUE 277if the counter is less than or equal to the test value and FALSE otherwise. 278If the test-type is not one of the named TESTTYPE constants, the request that 279initialized the trigger will return a Value error. A trigger with a counter 280value of <function>None</function> and a valid test-type is always TRUE. 281</para> 282 283<para> 284The WAITCONDITION type is simply a trigger with an associated event-threshold. 285The event threshold is used by the <function>Await</function> request to 286decide whether or not to generate an event to the client after the trigger has 287become TRUE. By setting the event-threshold to an appropriate value, it is 288possible to detect the situation where an <function>Await</function> request 289was processed after the TRIGGER became TRUE, which usually indicates that 290the server is not processing requests as fast as the client expects. 291</para> 292 293<para> 294The SYSTEMCOUNTER type provides the client with information about a 295<function>System</function>Counter. The name field is the textual name of 296the counter that identifies the counter to the client. The counter field 297is the client-side handle that should be used in requests that require a 298counter. The resolution field gives the approximate step size of the system 299counter. This is a hint to the client 300that the extension may not be able to resolve two wait conditions with test 301values that differ by less than this step size. A microsecond clock, for 302example, may advance in steps of 64 microseconds, so a counter based on this 303clock would have a resolution of 64. 304</para> 305 306<para> 307The only system counter that is guaranteed to be present is called SERVERTIME, 308which counts milliseconds from some arbitrary starting point. The least 309significant 32 bits of this counter track the value of Time used by the 310server in Events and Requests. Other system counters may be provided by 311different implementations of the extension. The X Consortium will maintain a 312registry of system counter names to avoid collisions in the name space. 313</para> 314 315<para> 316An ALARM is the client-side handle on an <function>Alarm</function> resource. 317</para> 318 319<para> 320The FENCE type defines the client-side handle on a server 321<function>Fence</function>. A fence can only be in one of two states, 322represented by a BOOL. If the value is TRUE, the fence is in the triggered 323state. Otherwise, the fence is in the not triggered state. 324</para> 325 326</sect1> 327 328<sect1 id='Errors'> 329<title>Errors</title> 330 331<variablelist> 332 <varlistentry> 333 <term>Counter</term> 334 <listitem> 335 <para> 336This error is generated if the value for a COUNTER argument in a request 337does not name a defined COUNTER. 338 </para> 339 </listitem> 340 </varlistentry> 341 <varlistentry> 342 <term>Alarm</term> 343 <listitem> 344 <para> 345This error is generated if the value for an ALARM argument in a request 346does not name a defined ALARM. 347 </para> 348 </listitem> 349 </varlistentry> 350 <varlistentry> 351 <term>Fence</term> 352 <listitem> 353 <para> 354This error is generated if the value for a FENCE argument in a request 355does not name a defined FENCE. 356 </para> 357 </listitem> 358 </varlistentry> 359</variablelist> 360 361</sect1> 362<sect1 id='Requests'> 363<title>Requests</title> 364 365<variablelist> 366 <varlistentry> 367 <term>Initialize</term> 368 <listitem> 369<literallayout class="monospaced"> 370version-major,version-minor: CARD8 371=> 372version-major,version-minor: CARD8 373</literallayout> 374 375 <para> 376This request must be executed before any other requests for this extension. If a 377client violates this rule, the results of all SYNC requests that it issues are 378undefined. The request takes the version number of the extension that the 379client wishes to use and returns the actual version number being implemented 380by the extension for this client. The extension may return different 381version numbers to a client depending of the version number supplied by 382that client. This request should be executed only once for each client 383connection. 384 </para> 385 <para> 386Given two different versions of the SYNC protocol, v1 and v2, v1 is 387compatible with v2 if and only if v1.version_major = v2.version_major 388and v1.version_minor <= v2.version_minor. Compatible means that the 389functionality is fully supported in an identical fashion in the two versions. 390 </para> 391 <para> 392This document describes major version 3, minor version 1 of the SYNC protocol. 393 </para> 394 </listitem> 395 </varlistentry> 396 <varlistentry> 397 <term>ListSystemCounters</term> 398 <listitem> 399<literallayout class="monospaced"> 400=> 401system-counters: LISTofSYSTEMCOUNTER 402Errors: Alloc 403</literallayout> 404 <para> 405This request returns a list of all the system counters that are available at 406the time the request is executed, which includes the system counters 407that are maintained by other extensions. The list returned by this 408request may change as counters are created and destroyed by other extensions. 409 </para> 410 </listitem> 411 </varlistentry> 412 <varlistentry> 413 <term>CreateCounter</term> 414 <listitem> 415<literallayout class="monospaced"> 416id: COUNTER 417initial-value: INT64 418Errors: IDChoice,Alloc 419</literallayout> 420 <para> 421This request creates a counter and assigns the specified id to it. The counter 422value is initialized to the specified initial-value and there are no clients 423waiting on the counter. 424 </para> 425 </listitem> 426 </varlistentry> 427 <varlistentry> 428 <term>DestroyCounter</term> 429 <listitem> 430<literallayout class="monospaced"> 431counter: COUNTER 432Errors: Counter,Access 433</literallayout> 434 <para> 435This request destroys the given counter and sets the counter fields for all 436triggers that specify this counter to <function>None</function>. All clients 437waiting on the counter are released and a <function>CounterNotify</function> 438event with the destroyed field set to TRUE is sent to each waiting client, 439regardless of the event-threshold. All alarms specifying the counter become 440<function>Inactive</function> and an <function>AlarmNotify</function> 441event with a state field of <function>Inactive</function> is generated. A 442counter is destroyed automatically when the connection to the creating client 443is closed down if the close-down mode is Destroy. An 444<function>Access</function> error is generated if counter is a system 445counter. A <function>Counter</function> error is generated if counter does 446not name a valid counter. 447 </para> 448 </listitem> 449 </varlistentry> 450 <varlistentry> 451 <term>QueryCounter</term> 452 <listitem> 453<literallayout class="monospaced"> 454counter: COUNTER 455=> 456value: INT64 457Errors: <function>Counter</function> 458</literallayout> 459 <para> 460This request returns the current value of the given counter or a generates 461Counter error if counter does not name a valid counter. 462 </para> 463 </listitem> 464 </varlistentry> 465 <varlistentry> 466 <term>Await</term> 467 <listitem> 468<literallayout class="monospaced"> 469wait-list: LISTofWAITCONDITION 470Errors: Counter,Alloc,Value 471</literallayout> 472 <para> 473When this request is executed, the triggers in the wait-list are initialized 474using the wait-value and value-type fields, as described in the definition of 475TRIGGER above. The processing of further requests for the client is blocked 476until one or more of the triggers becomes TRUE. This may happen immediately, 477as a result of the initialization, or at some later time, as a result of 478a subsequent <function>SetCounter</function>, 479<function>ChangeCounter</function> or 480<function>DestroyCounter</function> request. 481 </para> 482 <para> 483A Value error is generated if wait-list is empty. 484 </para> 485 <para> 486When the client becomes unblocked, each trigger is checked to determine 487whether a <function>CounterNotify</function> event should be generated. 488The difference between the counter and the test value is calculated by 489subtracting the test value from the value of the counter. If the test-type 490is <function>PositiveTransition</function> or 491<function>PositiveComparison</function>, a 492<function>CounterNotify</function> event is generated if the difference is 493at least event-threshold. If the test-type is 494<function>NegativeTransition</function> or 495<function>NegativeComparison</function>, a 496<function>CounterNotify</function> event is generated if the difference 497is at most event-threshold. If the difference lies outside the range for an 498INT64, an event is not generated. 499 </para> 500 <para> 501This threshold check is made for each trigger in the list and a 502<function>CounterNotify</function> event is generated for every trigger for 503which the check succeeds. The check for 504<function>CounterNotify</function> events is performed even if one of the 505triggers is TRUE when the request is first executed. Note that a 506<function>CounterNotify</function> event may be generated for a trigger 507that is FALSE if there are multiple triggers in the request. A 508<function>CounterNotify</function> event with the destroyed flag set to 509TRUE is always generated if the counter for one of the triggers is 510destroyed. 511 </para> 512 </listitem> 513 </varlistentry> 514 <varlistentry> 515 <term>ChangeCounter</term> 516 <listitem> 517<literallayout class="monospaced"> 518counter: COUNTER 519amount: INT64 520Errors: <function>Counter,Access,Value</function> 521</literallayout> 522 <para> 523This request changes the given counter by adding amount to the current 524counter value. If the change to this counter satisfies a trigger for which a client 525is waiting, that client is unblocked and one or more 526<function>CounterNotify</function> events may be generated. If the change to 527the counter satisfies the trigger for an alarm, an 528<function>AlarmNotify</function> event is generated and the 529alarm is updated. An <function>Access</function> error is generated if 530counter is a system counter. A <function>Counter</function> error is 531generated if counter does not name a valid counter. If the resulting value 532for the counter would be outside the range for an INT64, a 533<function>Value</function> error is generated and the counter is not changed. 534 </para> 535 <para> 536It should be noted that all the clients whose triggers are satisfied by this 537change are unblocked, so this request cannot be used to implement mutual 538exclusion. 539 </para> 540 </listitem> 541 </varlistentry> 542 <varlistentry> 543 <term>SetCounter</term> 544 <listitem> 545<literallayout class="monospaced"> 546counter: COUNTER 547value: INT64 548Errors: <function>Counter,Access</function> 549</literallayout> 550 <para> 551This request sets the value of the given counter to value. The effect is 552equivalent to executing the appropriate ChangeCounter request to change 553the counter value to value. An Access error is generated if counter names a 554system counter. A Counter error is generated if counter does not name a valid 555counter. 556 </para> 557 </listitem> 558 </varlistentry> 559 <varlistentry> 560 <term>CreateAlarm</term> 561 <listitem> 562<literallayout class="monospaced"> 563id: ALARM 564values-mask: CARD32 565values-list: LISTofVALUE 566left">Errors: IDChoice,Counter,Match,Value,Alloc 567</literallayout> 568 <para> 569This request creates an alarm and assigns the identifier id to it. The 570values-mask and values-list specify the attributes that are to be explicitly 571initialized. The attributes for an Alarm and their defaults are: 572 </para> 573 <informaltable frame="none"> 574 <?dbfo keep-together="always" ?> 575 <tgroup cols='4' align='left' colsep='0' rowsep='0'> 576 <colspec colname='c1' colwidth="1.0*" colsep='1'/> 577 <colspec colname='c2' colwidth="1.0*" colsep='1'/> 578 <colspec colname='c3' colwidth="1.0*"/> 579 <colspec colname='c4' colwidth="1.3*"/> 580 <thead> 581 <row rowsep='1'> 582 <entry>Attribute</entry> 583 <entry>Type</entry> 584 <entry namest='c3' nameend='c4'>Default</entry> 585 </row> 586 </thead> 587 <tbody> 588 <row> 589 <entry>trigger</entry> 590 <entry>TRIGGER</entry> 591 <entry>counter</entry> 592 <entry>None</entry> 593 </row> 594 <row> 595 <entry></entry> 596 <entry></entry> 597 <entry>value-type</entry> 598 <entry>Absolute</entry> 599 </row> 600 <row> 601 <entry></entry> 602 <entry></entry> 603 <entry>value</entry> 604 <entry>0</entry> 605 </row> 606 <row> 607 <entry></entry> 608 <entry></entry> 609 <entry>test-type</entry> 610 <entry>PositiveComparison</entry> 611 </row> 612 <row> 613 <entry>delta</entry> 614 <entry>INT64</entry> 615 <entry>1</entry> 616 </row> 617 <row> 618 <entry>events</entry> 619 <entry>BOOL</entry> 620 <entry>TRUE</entry> 621 </row> 622 </tbody> 623 </tgroup> 624 </informaltable> 625 <para> 626The trigger is initialized as described in the definition of TRIGGER, with an 627error being generated if necessary. 628 </para> 629 <para> 630If the counter is <function>None</function>, the state of the alarm is set 631to <function>Inactive</function>, else it is set to Active. 632 </para> 633 <para> 634Whenever the trigger becomes TRUE, either as a result of this request or as the 635result of a <function>SetCounter</function>, 636<function>ChangeCounter</function>, <function>DestroyCounter</function>, or 637<function>ChangeAlarm</function> request, an 638<function>AlarmNotify</function> event is generated and the alarm is 639updated. The alarm is updated by repeatedly adding delta to the value of the 640trigger and reinitializing it until it becomes FALSE. If this update would 641cause value to fall outside the range for an INT64, or if the counter 642value is <function>None</function>, or if the delta is 0 and test-type 643is <function>PositiveComparison</function> or 644<function>NegativeComparison</function>, no change is made to value and 645the alarm state is changed to <function>Inactive</function> before the 646event is generated. No further events are generated by an 647<function>Inactive</function> alarm until a <function>ChangeAlarm</function> 648or <function>DestroyAlarm </function> request is executed. 649 </para> 650 <para> 651If the test-type is <function>PositiveComparison</function> or 652<function>PositiveTransition and</function> delta is less than zero, or 653if the test-type is <function>NegativeComparison</function> or 654<function>NegativeTransition</function> and delta is greater than zero, 655a <function>Match</function> error is generated. 656 </para> 657 <para> 658The events value enables or disables delivery of 659<function>AlarmNotify</function> events 660to the requesting client. The alarm keeps a separate event flag for 661each client so that other clients may select to receive events from this 662alarm. 663 </para> 664 <para> 665An <function>AlarmNotify</function> event is always generated at some time 666after the execution of a <function>CreateAlarm</function> request. This 667will happen immediately if the trigger is TRUE, or it will happen later 668when the trigger becomes TRUE or the Alarm is destroyed. 669 </para> 670 </listitem> 671 </varlistentry> 672 <varlistentry> 673 <term>ChangeAlarm</term> 674 <listitem> 675<literallayout class="monospaced"> 676id: ALARM 677values-mask: CARD32 678values-list: LISTofVALUE 679Errors: Alarm,Counter,Value,Match 680</literallayout> 681 <para> 682This request changes the parameters of an Alarm. All of the parameters 683specified for the <function>CreateAlarm</function> request may be changed 684using this request. The trigger is reinitialized and an 685<function>AlarmNotify</function> event is generated if appropriate, as 686explained in the description of the <function>CreateAlarm</function> request. 687 </para> 688 <para> 689Changes to the events flag affect the event delivery to the requesting 690client only and may be used by a client to select or deselect event delivery 691from an alarm created by another client. 692 </para> 693 <para> 694The order in which attributes are verified and altered is server-dependent. 695If an error is generated, a subset of the attributes may have been altered. 696 </para> 697 </listitem> 698 </varlistentry> 699 <varlistentry> 700 <term>DestroyAlarm</term> 701 <listitem> 702<literallayout class="monospaced"> 703alarm: ALARM 704Errors: Alarm 705</literallayout> 706 <para> 707This request destroys an alarm. An alarm is automatically destroyed when the 708creating client is closed down if the close-down mode is 709<function>Destroy</function>. When an alarm is destroyed, an 710<function>AlarmNotify</function> event is generated with a state value of 711<function>Destroyed</function>. 712 </para> 713 </listitem> 714 </varlistentry> 715 <varlistentry> 716 <term>QueryAlarm</term> 717 <listitem> 718<literallayout class="monospaced"> 719alarm: ALARM 720=> 721trigger: TRIGGER 722delta: INT64 723events: ALARMEVENTMASK 724state: ALARMSTATE 725Errors: <function>Alarm</function> 726</literallayout> 727 <para>This request retrieves the current parameters for an Alarm.</para> 728 </listitem> 729 </varlistentry> 730 <varlistentry> 731 <term>SetPriority</term> 732 <listitem> 733<literallayout class="monospaced"> 734client-resource: XID 735priority: INT32 736Errors: <function>Match</function> 737</literallayout> 738 <para> 739This request changes the scheduling priority of the client that created 740client-resource. If client-resource is <function>None</function>, then 741the priority for the client making the request is changed. A 742<function>Match</function> error is generated if client-resource is not 743<function>None</function> and does not name an existing resource in the 744server. For any two priority values, A and B, A is higher priority if 745and only if A is greater than B. 746 </para> 747 <para> 748The priority of a client is set to 0 when the initial client connection is 749 made. 750 </para> 751 <para> 752The effect of different client priorities depends on the particular 753implementation of the extension, and in some cases it may have no effect at 754all. However, the intention is that higher priority clients will have 755their requests executed before those of lower priority clients. 756 </para> 757 <para> 758For most animation applications, it is desirable that animation clients be 759given priority over nonrealtime clients. This improves the smoothness of the 760animation on a loaded server. Because a server is free to implement very strict 761priorities, processing requests for the highest priority client to the 762exclusion of all others, it is important that a client that may potentially 763monopolize the whole server, such as an animation that produces continuous 764output as fast as it can with no rate control, is run at low rather than high 765priority. 766 </para> 767 </listitem> 768 </varlistentry> 769 <varlistentry> 770 <term>GetPriority</term> 771 <listitem> 772<literallayout class="monospaced"> 773client-resource: XID 774=> 775priority: INT32 776Errors: <function>Match</function> 777</literallayout> 778 <para> 779This request returns the scheduling priority of the client that created 780client-resource. If client-resource is <function>None</function>, then the 781priority for the client making the request is returned. A 782<function>Match</function> error is generated if client-resource is 783not <function>None</function> and does not name an existing resource in the 784server. 785 </para> 786 </listitem> 787 </varlistentry> 788 <varlistentry> 789 <term>CreateFence</term> 790 <listitem> 791<literallayout class="monospaced"> 792drawable: DRAWABLE 793id: FENCE 794initially-triggered: BOOL 795Errors: <function>IDChoice</function>,<function>Alloc</function> 796</literallayout> 797 <para> 798This request creates a fence on the screen associated with drawable and 799assigns the specified id to it. The fence is in the triggered state iff 800initially-triggered is TRUE. There are no clients waiting on the fence. 801 </para> 802 </listitem> 803 </varlistentry> 804 <varlistentry> 805 <term>TriggerFence</term> 806 <listitem> 807<literallayout class="monospaced"> 808fence: FENCE 809Errors: <function>Fence</function> 810</literallayout> 811 <para> 812This request puts the given fence in the triggered state after all rendering 813from previous requests that affects resources owned by the fence's screen has 814completed. This includes requests from other clients if those requests have 815been dispatched. This request has no visible effects if the fence was already 816in the triggered state. A <function>Fence</function> error is generated if 817fence does not name a valid fence. 818 </para> 819 <para> 820Note that the given fence's state is not necessarily directly modified by this 821request. The state change need only be queued to occur after the required 822rendering has completed. Clients should take care to not assume the fence will 823be in the triggered state in subsequent requests, such as those that operate 824on the given fence immediately. <function>AwaitFence</function> should first 825be issued if subsequent requests require the fence to be in the triggered 826state. 827 </para> 828 </listitem> 829 </varlistentry> 830 <varlistentry> 831 <term>ResetFence</term> 832 <listitem> 833<literallayout class="monospaced"> 834fence: FENCE 835Errors: <function>Fence</function>,<function>Match</function> 836</literallayout> 837 <para> 838This request immediately puts the given fence in the not triggered state. 839A <function>Match</function> error is generated if the fence is not in the 840triggered state. A <function>Fence</function> error is generated if fence 841does not name a valid fence. 842 </para> 843 <para> 844See the warnings above regarding <function>TriggerFence</function>'s delayed 845effect. In particular, a <function>TriggerFence</function> request 846immediately followed by a <function>ResetFence</function> request is likely 847to result in a <function>Match</function> error. An 848<function>AwaitFence</function> request should be issued between the two. 849 </para> 850 </listitem> 851 </varlistentry> 852 <varlistentry> 853 <term>DestroyFence</term> 854 <listitem> 855<literallayout class="monospaced"> 856fence: FENCE 857Errors: <function>Fence</function> 858</literallayout> 859 <para> 860This request destroys the given fence. All clients waiting on this fence are 861released. A fence is destroyed automatically when the connection to the client 862that created the fence is closed if the close-down mode is 863<function>DestroyAll</function>. A <function>Fence</function> error is 864generated if fence does not name a valid fence. 865 </para> 866 </listitem> 867 </varlistentry> 868 <varlistentry> 869 <term>QueryFence</term> 870 <listitem> 871<literallayout class="monospaced"> 872fence: FENCE 873=> 874triggered: BOOL 875Errors: <function>Fence</function> 876</literallayout> 877 <para> 878This request returns TRUE if the given fence is triggered, or FALSE if it 879is not triggered. A <function>Fence</function> error is generated if 880fence does not name a valid fence. 881 </para> 882 </listitem> 883 </varlistentry> 884 <varlistentry> 885 <term>AwaitFence</term> 886 <listitem> 887<literallayout class="monospaced"> 888fence-list: LISTofFENCE 889Errors: <function>Fence</function>,<function>Alloc</function> 890</literallayout> 891 <para> 892When this request is executed, the processing of further requests for the 893client is blocked until one or more of the fences in fence-list reaches the 894triggered state. If any of the fences are already in the triggered state, 895request processing resumes immediately. A <function>Fence</function> error 896is generated if any member of fence-list does not name a valid fence. 897 </para> 898 </listitem> 899 </varlistentry> 900</variablelist> 901</sect1> 902 903<sect1 id='Events'> 904<title>Events</title> 905 906<variablelist> 907 <varlistentry> 908 <term>CounterNotify</term> 909 <listitem> 910<literallayout class="monospaced"> 911counter: COUNTER 912wait-value: INT64 913counter-value: INT64 914time: TIME 915count: CARD16 916destroyed: BOOL 917</literallayout> 918 <para> 919<function>CounterNotify</function> events may be generated when a client 920becomes unblocked after an <function>Await</function> request has been 921processed. The wait-value is the value being waited for, and counter-value 922is the actual value of the counter at the time the event was generated. 923The destroyed flag is TRUE if this request was generated as the result of 924the destruction of the counter and FALSE otherwise. The time is the server 925time at which the event was generated. 926 </para> 927 <para> 928When a client is unblocked, all the <function>CounterNotify</function> 929events for the Await request are generated contiguously. If count is 0, 930there are no more events to follow for this request. If count is n, 931there are at least n more events to follow. 932 </para> 933 </listitem> 934 </varlistentry> 935 <varlistentry> 936 <term>AlarmNotify</term> 937 <listitem> 938<literallayout class="monospaced"> 939alarm: ALARM 940counter-value: INT64 941alarm-value: INT64 942state: ALARMSTATE 943time: TIME 944</literallayout> 945 <para> 946An <function>AlarmNotify</function> event is generated when an alarm is 947triggered. alarm-value is the test value of the trigger in the alarm when 948it was triggered, counter-value is the value of the counter that triggered 949the alarm, and time is the server time at which the event was generated. 950The state is the new state of the alarm. If state is 951<function>Inactive</function>, no more events will be generated by this 952alarm until a <function>ChangeAlarm</function> request is executed, the alarm 953is destroyed, or the counter for the alarm is destroyed. 954 </para> 955 </listitem> 956 </varlistentry> 957</variablelist> 958</sect1> 959</chapter> 960 961<chapter id='Encoding'> 962<title>Encoding</title> 963<para> 964Please refer to the X11 Protocol Encoding document as this section uses 965syntactic conventions established there and references types defined there. 966</para> 967<para>The name of this extension is "SYNC".</para> 968 969<sect1 id='Encoding_New_Types'> 970<title>Encoding New Types</title> 971<para> 972The following new types are used by the extension. 973</para> 974 975<literallayout class="monospaced"> 976ALARM: CARD32 977ALARMSTATE: 978 0 Active 979 1 Inactive 980 2 Destroyed 981COUNTER: CARD32 982INT64: 64-bit signed integer 983SYSTEMCOUNTER: 984 4 COUNTER counter 985 8 INT64 resolution 986 2 n length of name in bytes 987 n STRING8 name 988 p pad,p=pad(n+2) 989TESTTYPE: 990 0 PositiveTransition 991 1 NegativeTransition 992 2 PositiveComparison 993 3 NegativeComparison 994TRIGGER: 995 4 COUNTER counter 996 4 VALUETYPE wait-type 997 8 INT64 wait-value 998 4 TESTTYPE test-type VALUETYPE: 999 0 Absolute 1000 1 Relative 1001WAITCONDITION: 1002 20 TRIGGER trigger 1003 8 INT64 event threshold 1004FENCE: CARD32 1005</literallayout> 1006 1007<para> 1008An INT64 is encoded in 8 bytes with the most significant 4 bytes 1009first followed by the least significant 4 bytes. Within these 4-byte 1010groups, the byte ordering determined during connection setup is used. 1011</para> 1012</sect1> 1013 1014<sect1 id='Encoding_Errors'> 1015<title>Encoding Errors</title> 1016<literallayout class="monospaced"> 1017<function>Counter</function> 1018 1 0 Error 1019 1 Base + 0 code 1020 2 CARD16 sequence number 1021 4 CARD32 bad counter 1022 2 CARD16 minor opcode 1023 1 CARD8 major opcode 1024 21 unused 1025<function>Alarm</function> 1026 1 0 Error 1027 1 Base + 1 code 1028 2 CARD16 sequence number 1029 4 CARD32 bad alarm 1030 2 CARD16 minor opcode 1031 1 CARD8 major opcode 1032 21 unused 1033<function>Fence</function> 1034 1 0 Error 1035 1 Base + 2 code 1036 2 CARD16 sequence number 1037 4 CARD32 bad fence 1038 2 CARD16 minor opcode 1039 1 CARD8 major opcode 1040 21 unused 1041</literallayout> 1042 1043</sect1> 1044 1045<sect1 id='Encoding_Requests'> 1046<title>Encoding Requests</title> 1047 1048<literallayout class="monospaced"> 1049<function>Initialize</function> 1050 1 CARD8 major opcode 1051 1 0 minor opcode 1052 2 2 request length 1053 1 CARD8 major version 1054 1 CARD8 minor version 1055 2 unused 1056=> 1057 1 1 Reply 1058 1 unused 1059 2 CARD16 sequence number 1060 4 0 reply length 1061 1 CARD8 major version 1062 1 CARD8 minor version 1063 2 unused 1064 20 unused 1065 1066<function>ListSystemCounters</function> 1067 1 CARD8 major opcode 1068 1 1 minor opcode 1069 2 1 request length 1070=> 1071 1 1 Reply 1072 1 unused 1073 2 CARD16 sequence number 1074 4 0 reply length 1075 4 INT32 list length 1076 20 unused 1077 4n list of SYSTEMCOUNTER system counters 1078 1079<function>CreateCounter</function> 1080 1 CARD8 major opcode 1081 1 2 minor opcode 1082 2 4 request length 1083 4 COUNTER id 1084 8 INT64 initial value 1085 1086<function>DestroyCounter</function> 1087 1 CARD8 major opcode 1088 1 6 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode</para></footnote> 1089 2 2 request length 1090 4 COUNTER counter 1091=> 1092 1 1 Reply 1093 1 unused 1094 2 CARD16 sequence number 1095 4 0 reply length 1096 8 INT64 counter value 1097 16 unused 1098 1099Await 1100 1 CARD8 major opcode 1101 1 7 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote> 1102 2 1 + 7*n request length 1103 28n LISTofWAITCONDITION wait conditions 1104 1105ChangeCounter 1106 1 CARD8 major opcode 1107 1 4 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote> 1108 2 4 request length 1109 4 COUNTER counter 1110 8 INT64 amount 1111 1112SetCounter 1113 1 CARD8 major opcode 1114 1 3 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote> 1115 2 4 request length 1116 4 COUNTER counter 1117 8 INT64 value 1118 1119CreateAlarm 1120 1 CARD8 major opcode 1121 1 8 minor opcode 1122 2 3+n request length 1123 4 ALARM id 1124 4 BITMASK values mask 1125 1126 #x00000001 counter 1127 #x00000002 value-type 1128 #x00000004 value 1129 #x00000008 test-type 1130 #x00000010 delta 1131 #x00000020 events 1132 1133 4n LISTofVALUE values 1134 1135VALUES 1136 4 COUNTER counter 1137 4 VALUETYPE value-type 1138 8 INT64 value 1139 4 TESTTYPE test-type 1140 8 INT64 delta 1141 4 BOOL events 1142 1143ChangeAlarm 1144 1 CARD8 major opcode 1145 1 9 minor opcode 1146 2 3+n request length 1147 4 ALARM id 1148 4 BITMASK values mask 1149 encodings as for <function>CreateAlarm</function> 1150 4n LISTofVALUE values 1151 encodings as for <function>CreateAlarm</function> 1152 1153DestroyAlarm 1154 1 CARD8 major opcode 1155 1 11 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote> 1156 2 2 request length 1157 4 ALARM alarm 1158 1159QueryAlarm 1160 1 CARD8 major opcode 1161 1 10 minor opcode<footnote><para>A previous version of this document gave an incorrect minor opcode.</para></footnote> 1162 2 2 request length 1163 4 ALARM alarm 1164=> 1165 1 1 Reply 1166 1 unused 1167 2 CARD16 sequence number 1168 4 2 reply length 1169 20 TRIGGER trigger 1170 8 INT64 delta 1171 1 BOOL events 1172 1 ALARMSTATE state 1173 2 unused 1174 1175SetPriority 1176 1 CARD8 major opcode 1177 1 12 minor opcode 1178 2 3 request length 1179 4 CARD32 id 1180 4 INT32 priority 1181 1182GetPriority 1183 1 CARD8 major opcode 1184 1 13 minor opcode 1185 2 1 request length 1186 4 CARD32 id 1187=> 1188 1 1 Reply 1189 1 unused 1190 2 CARD16 sequence number 1191 4 0 reply length 1192 4 INT32 priority 1193 20 unused 1194 1195CreateFence 1196 1 CARD8 major opcode 1197 1 14 minor opcode 1198 2 4 request length 1199 4 DRAWABLE drawable 1200 4 FENCE id 1201 1 BOOL initially triggered 1202 3 unused 1203 1204TriggerFence 1205 1 CARD8 major opcode 1206 1 15 minor opcode 1207 2 2 request length 1208 4 FENCE id 1209 1210ResetFence 1211 1 CARD8 major opcode 1212 1 16 minor opcode 1213 2 2 request length 1214 4 FENCE id 1215 1216DestroyFence 1217 1 CARD8 major opcode 1218 1 17 minor opcode 1219 2 2 request length 1220 4 FENCE id 1221 1222QueryFence 1223 1 CARD8 major opcode 1224 1 18 minor opcode 1225 2 2 request length 1226 4 FENCE id 1227=> 1228 1 1 Reply 1229 1 unused 1230 2 CARD16 sequence number 1231 4 0 reply length 1232 1 BOOL triggered 1233 23 unused 1234 1235AwaitFence 1236 1 CARD8 major opcode 1237 1 19 minor opcode 1238 2 1 + n request length 1239 4*n LISTofFENCE wait conditions 1240 1241</literallayout> 1242 1243</sect1> 1244 1245<sect1 id='Encoding_Events'> 1246<title>Encoding Events</title> 1247 1248<literallayout class="monospaced"> 1249<function>CounterNotify</function> 1250 1 Base + 0 code 1251 1 0 kind 1252 2 CARD16 sequence number 1253 4 COUNTER counter 1254 8 INT64 wait value 1255 8 INT64 counter value 1256 4 TIME timestamp 1257 2 CARD16 count 1258 1 BOOL destroyed 1259 1 unused 1260 1261<function>AlarmNotify</function> 1262 1 Base + 1 code 1263 1 1 kind 1264 2 CARD16 sequence number 1265 4 ALARM alarm 1266 8 INT64 counter value 1267 8 INT64 alarm value 1268 4 TIME timestamp 1269 1 ALARMSTATE state 1270 3 unused 1271</literallayout> 1272</sect1> 1273</chapter> 1274</book> 1275