specs/synclib.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5
   6 <!-- lifted from troff+ms+XMan by doclifter -->
   7 <book id="recordlib">
   8
   9 <bookinfo>
  10    <title>X Synchronization Extension Library</title>
  11    <subtitle>X Consortium Standard</subtitle>
  12    <releaseinfo>X Version 11, Release 6.4</releaseinfo>
  13    <authorgroup>
  14       <author>
  15         <firstname>Tim</firstname><surname>Glauert</surname>
  16         <affiliation><orgname>Olivetti Research/MultiWorks</orgname></affiliation>
  17       </author>
  18       <othercredit>
  19           <firstname>Dave</firstname>
  20           <surname>Carver</surname>
  21           <affiliation><orgname>Digital EquipmentCorporation, MIT/Project Athena</orgname></affiliation>
  22       </othercredit>
  23       <othercredit>
  24         <firstname>Jim</firstname>
  25         <surname>Gettys</surname>
  26         <affiliation><orgname>Digital EquipmentCorporation, Cambridge Research Laboratory</orgname></affiliation>
  27       </othercredit>
  28       <othercredit>
  29         <firstname>David</firstname>
  30         <surname>Wiggins</surname>
  31         <affiliation><orgname>X Consortium, Inc.</orgname></affiliation>
  32       </othercredit>
  33    </authorgroup>
  34    <copyright><year>1991</year><holder>Olivetti Research Limited, Cambridge England and Digital Equipment Corporation, Maynard, Massachusetts</holder></copyright>
  35    <copyright><year>1991</year><holder>X Consortium</holder></copyright>
  36    <releaseinfo>Version 3.0</releaseinfo>
  37    <affiliation><orgname>X Consortium</orgname></affiliation>
  38    <productnumber>X Version 11, Release 6.4</productnumber>
  39 <legalnotice>
  40
  41 <para>
  42 Permission to use, copy, modify, and distribute this documentation for any
  43 purpose and without fee is hereby granted, provided that the above
  44 copyright notice appear in all copies. Olivetti, Digital, MIT, and the
  45 X Consortium make no representations about the suitability for any purpose
  46 of the information in this document. This documentation is provided as
  47 is without express or implied warranty.
  48 </para>
  49
  50 <para>
  51 Permission is hereby granted, free of charge, to any person obtaining
  52 a copy of this software and associated documentation files
  53 (the "Software"), to deal in the Software without
  54 restriction, including without limitation the rights to use, copy,
  55 modify, merge, publish, distribute, sublicense, and/or sell copies of
  56 the Software, and to permit persons to whom the Software is furnished
  57 to do so, subject to the following conditions:
  58 </para>
  59
  60 <para>
  61 The above copyright notice and this permission notice shall be included in
  62 all copies or substantial portions of the Software.
  63 </para>
  64
  65 <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  66 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  67 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  68 IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  69 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  70 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  71 OTHER DEALINGS IN THE SOFTWARE.
  72 </para>
  73
  74 <para>
  75 Except as contained in this notice, the name of the X Consortium shall
  76 not be used in advertising or otherwise to promote the sale, use or other
  77 dealings in this Software without prior written authorization from the
  78 X Consortium.
  79 </para>
  80
  81 </legalnotice>
  82 </bookinfo>
  83
  84 <chapter id="synchronization_protocol">
  85 <title>Synchronization Protocol</title>
  86
  87 <para>
  88 The core X protocol makes no guarantees about the relative order of
  89 execution of requests for different clients.  This means that any
  90 synchronization between clients must be done at the client level in an
  91 operating system-dependent and network-dependent manner. Even if there
  92 was an accepted standard for such synchronization, the use of a network
  93 introduces unpredictable delays between the synchronization of the clients and
  94 the delivery of the resulting requests to the X server.
  95 </para>
  96 <para>
  97 The core X protocol also makes no guarantees about the time at which
  98 requests are executed, which means that all clients with real-time constraints
  99 must implement their timing on the host computer. Any such timings are
 100 subject to error introduced by delays within the operating system and
 101 network and are ineﬃcient because of the need for round-trip requests that
 102 keep the client and server synchronized.
 103 </para>
 104 <para>
 105 The synchronization extension provides primitives that allow synchronization
 106 between clients to take place entirely within the X server. This removes any
 107 error introduced by the network and makes it possible to synchronize clients
 108 on different hosts running different operating systems. This is important for
 109 multimedia applications, where audio, video, and graphics data streams are
 110 being synchronized. The extension also provides internal timers within the X
 111 server to which client requests can be synchronized. This allows simple
 112 animation applications to be implemented without any round-trip requests
 113 and makes best use of buffering within the client, network, and server.
 114 </para>
 115
 116 <sect1 id="description">
 117 <title>Description</title>
 118 <para>
 119 The mechanism used by this extension for synchronization within the X server
 120 is to block the processing of requests from a client until a specific
 121 synchronization condition occurs. When the condition occurs, the client is
 122 released and processing of requests continues. Multiple clients may block on
 123 the same condition to give inter-client synchronization. Alternatively, a single
 124 client may block on a condition such as an animation frame marker.
 125 </para>
 126 <para>
 127 The extension adds <function>Counter</function> and
 128 <function>Alarm</function> to the set of resources managed by
 129 the server. A counter has a 64-bit integer value that may be increased or
 130 decreased by client requests or by the server internally. A client can
 131 block by sending an <function>Await</function> request that waits until
 132 one of a set of synchronization conditions, called TRIGGERs, becomes TRUE.
 133 </para>
 134 <para>
 135 The <function>CreateCounter</function> request allows a client to create
 136 a <function>Counter</function> that can be changed by explicit
 137 <function>SetCounter</function> and <function>ChangeCounter</function>
 138 requests. These can be used to implement synchronization between
 139 different clients.
 140 </para>
 141 <para>
 142 There are some counters, called <function>System Counters</function>,
 143 that are changed by the server internally rather than by client
 144 requests. The effect of any change to a system counter is not visible
 145 until the server has finished processing the current request. In other
 146 words, system counters are apparently updated in the gaps between the
 147 execution of requests rather than during the actual execution of a
 148 request. The extension provides a system counter that advances with the
 149 server time as defined by the core protocol, and it may also provide
 150 counters that advance with the real-world time or that change each
 151 time the CRT screen is refreshed. Other extensions may provide their own
 152 extension-specific system counters.
 153 </para>
 154 <para>
 155 The extension provides an <function>Alarm</function> mechanism that allows clients to receive an
 156 event on a regular basis when a particular counter is changed.
 157 </para>
 158 </sect1>
 159 </chapter>
 160
 161 <chapter id="c_language_binding">
 162 <title>C Language Binding</title>
 163
 164 <para>
 165 The C routines provide direct access to the protocol and add no additional
 166 semantics.
 167 </para>
 168 <para>
 169 The include file for this extension is &lt;X11/extensions/sync.h&gt;.
 170 Most of the names in the language binding are derived from the protocol
 171 names by prepending XSync to the protocol name and changing the
 172 capitalization.
 173 </para>
 174
 175 <sect1 id="c_functions">
 176 <title>C Functions</title>
 177
 178 <para>
 179 Most of the following functions generate SYNC protocol requests.
 180 </para>
 181
 182 <funcsynopsis>
 183 <funcprototype>
 184   <funcdef>Status <function>XSyncQueryExtension</function></funcdef>
 185     <paramdef>Display <parameter> *dpy</parameter></paramdef>
 186     <paramdef>int <parameter> *event_base_return</parameter></paramdef>
 187     <paramdef>int <parameter> *error_base_return</parameter></paramdef>
 188 </funcprototype>
 189 </funcsynopsis>
 190
 191 <para>
 192 If dpy supports the SYNC extension,
 193 <function>XSyncQueryExtension</function> returns True,
 194 sets *event_base_return to the event number for the first SYNC event, and
 195 sets *error_base_return to the error number for the first SYNC error. If dpy
 196 does not support the SYNC extension, it returns False.
 197 </para>
 198
 199 <funcsynopsis>
 200 <funcprototype>
 201   <funcdef>Status <function>XSyncInitialize</function></funcdef>
 202     <paramdef>Display <parameter> *dpy</parameter></paramdef>
 203     <paramdef>int <parameter> *major_version_return</parameter></paramdef>
 204     <paramdef>int <parameter> *minor_version_return</parameter></paramdef>
 205 </funcprototype>
 206 </funcsynopsis>
 207
 208 <para>
 209 <function>XSyncInitialize</function> sets *major_version_return and
 210 *minor version return to the major/minor SYNC protocol version supported
 211 by the server. If the XSync library is compatible with the version
 212 returned by the server, this function returns <function>True</function>.
 213 If dpy does not support the SYNC extension, or if there was an error
 214 during communication with the server, or if the server and library protocol
 215 versions are incompatible, this function returns <function>False</function>.
 216 The only XSync function that may be called before this function is
 217 XSyncQueryExtension. If a client violates this rule, the effects of all XSync
 218 calls that it makes are undefined.
 219 </para>
 220
 221 <funcsynopsis>
 222 <funcprototype>
 223   <funcdef>XSyncSystemCounter *<function>XSyncListSystemCounters</function></funcdef>
 224     <paramdef>Display <parameter> *dpy</parameter></paramdef>
 225     <paramdef>int <parameter> *n_counters_return</parameter></paramdef>
 226 </funcprototype>
 227 </funcsynopsis>
 228
 229 <para>
 230 <function>XSyncListSystemCounters</function> returns a pointer to an array
 231 of system counters supported by the display and sets *n_counters_return
 232 to the number of counters in the array.  The array should be freed with
 233 <function>XSyncFreeSystemCounterList</function>. If dpy does not support
 234 the SYNC extension, or if there was an error during communication with
 235 the server, or if the server does not support any system counters,
 236 this function returns NULL.
 237 </para>
 238
 239 <para>
 240 XSyncSystemCounter has the following fields:
 241 </para>
 242
 243 <literallayout remap='Ds'>
 244 char *              name;        /* null-terminated name of system counter */
 245 XSyncCounter        counter;     /* counter id of this system counter */
 246 XSyncValue          resolution;  /* resolution of this system counter */
 247 </literallayout>
 248
 249 <funcsynopsis>
 250 <funcprototype>
 251   <funcdef>void <function>XSyncFreeSystemCounterList</function></funcdef>
 252     <paramdef>XSyncSystemCounter <parameter> *list</parameter></paramdef>
 253 </funcprototype>
 254 </funcsynopsis>
 255
 256 <para>
 257 <function>XSyncFreeSystemCounterList</function> frees the memory
 258 associated with the system counter list returned by
 259 <function>XSyncListSystemCounters</function>.
 260 </para>
 261
 262 <funcsynopsis>
 263 <funcprototype>
 264   <funcdef>XSyncCounter <function>XSyncCreateCounter</function></funcdef>
 265     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 266     <paramdef>XSyncValue<parameter> initial_value</parameter></paramdef>
 267 </funcprototype>
 268 </funcsynopsis>
 269
 270 <para>
 271 <function>XSyncCreateCounter</function> creates a counter on the dpy
 272 with the given initial value and returns the counter ID. It returns
 273 <function>None</function> if dpy does not support the SYNC extension.
 274 </para>
 275
 276 <funcsynopsis>
 277 <funcprototype>
 278   <funcdef>Status <function>XSyncSetCounter</function></funcdef>
 279     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 280     <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>
 281     <paramdef>XSyncValue<parameter> value</parameter></paramdef>
 282 </funcprototype>
 283 </funcsynopsis>
 284
 285
 286 <para>
 287 <function>XSyncSetCounter</function> sets counter to value. It returns
 288 <function>False </function> if dpy does not
 289 support the SYNC extension; otherwise, it returns <function>True</function>.
 290 </para>
 291
 292 <funcsynopsis>
 293 <funcprototype>
 294   <funcdef>Status <function>XSyncChangeCounter</function></funcdef>
 295     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 296     <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>
 297     <paramdef>XSyncValue<parameter> value</parameter></paramdef>
 298 </funcprototype>
 299 </funcsynopsis>
 300
 301 <para>
 302 <function>XSyncChangeCounter</function> adds value to counter. It returns
 303 <function>False</function> if dpy does not support the SYNC extension;
 304 otherwise, it returns
 305 <function>True</function>.
 306 </para>
 307 <funcsynopsis>
 308 <funcprototype>
 309   <funcdef>Status <function>XSyncDestroyCounter</function></funcdef>
 310     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 311     <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>
 312 </funcprototype>
 313 </funcsynopsis>
 314
 315 <para>
 316 <function>XSyncDestroyCounter</function> destroys counter. It returns
 317 <function>False</function> if dpy does not support the SYNC extension;
 318 otherwise, it returns <function>True</function>.
 319 </para>
 320
 321 <funcsynopsis>
 322 <funcprototype>
 323   <funcdef>Status <function>XSyncQueryCounter</function></funcdef>
 324     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 325     <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>
 326     <paramdef>XSyncValue<parameter> *value_return</parameter></paramdef>
 327 </funcprototype>
 328 </funcsynopsis>
 329
 330 <para>
 331 <function>XSyncQueryCounter</function> sets *value_return to the current
 332 value of counter. It returns <function>False</function> if there was an
 333 error during communication with the server or if dpy does not support the
 334 SYNC extension; otherwise, it returns <function>True</function>.
 335 </para>
 336
 337 <funcsynopsis>
 338 <funcprototype>
 339   <funcdef>Status <function>XSyncAwait</function></funcdef>
 340     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 341     <paramdef>XSyncWaitCondition<parameter> *wait_list</parameter></paramdef>
 342     <paramdef>int<parameter> n_conditions</parameter></paramdef>
 343 </funcprototype>
 344 </funcsynopsis>
 345
 346 <para>
 347 <function>XSyncAwait</function> awaits on the conditions in wait_list.
 348 The n_conditions is the number of wait conditions in wait_list. It
 349 returns <function>False</function> if dpy does not support the SYNC
 350 extension; otherwise, it returns <function>True</function>. The await is
 351 processed asynchronously by the server; this function always returns
 352 immediately after issuing the request.
 353 </para>
 354 <para>
 355 XSyncWaitCondition has the following fields:
 356 </para>
 357
 358 <literallayout remap='Ds'>
 359 XSyncCounter     trigger.counter;    /*counter to trigger on */
 360 XSyncValueType   trigger.value_type; /*absolute/relative */
 361 XSyncValue       trigger.wait_value; /*value to compare counter to */
 362 XSyncTestType    trigger.test_type;  /*pos/neg comparison/transtion */
 363 XSyncValue       event_threshold;    /*send event if past threshold */
 364 </literallayout>
 365
 366 <para>
 367 <function>XSyncValueType</function> can be either
 368 <function>XSyncAbsolute</function> or <function>XSyncRelative</function>.
 369 </para>
 370
 371 <para>
 372 <function>XSyncTestType</function> can be one of
 373 <function>XSyncPositiveTransition</function>,
 374 <function>XSyncNegativeTransition</function>,
 375 <function>XSyncPositiveComparison</function>, or
 376 <function>XSyncNegativeComparison</function>.
 377 </para>
 378
 379 <funcsynopsis>
 380 <funcprototype>
 381   <funcdef>XSyncAlarm <function>XSyncCreateAlarm</function></funcdef>
 382     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 383     <paramdef>unsigned long<parameter> values_mask</parameter></paramdef>
 384     <paramdef>XSyncAlarmAttributes<parameter> *values`</parameter></paramdef>
 385 </funcprototype>
 386 </funcsynopsis>
 387
 388 <para>
 389 <function>XSyncCreateAlarm</function> creates an alarm and returns the
 390 alarm ID. It returns None if the display does not support the SYNC
 391 extension. The values_mask and values specify the alarm attributes.
 392 </para>
 393
 394 <para>
 395 <function>XSyncAlarmAttributes</function> has the following fields. The
 396 attribute_mask column specifies the symbol that the caller should OR
 397 into values_mask to indicate that the value for the corresponding
 398 attribute was actually supplied. Default values are used for all
 399 attributes that do not have their attribute_mask OR’ed into values_mask.
 400 See the protocol description for <function>CreateAlarm</function> for the
 401 defaults.
 402 </para>
 403
 404 <literallayout remap='Ds'>
 405 type                 field name           attribute_mask
 406 XSyncCounter       trigger.counter;     XSyncCACounter
 407 XSyncValueType     trigger.value_type;  XSyncCAValueType
 408 XSyncValue         trigger.wait_value;  XSyncCAValue
 409 XSyncTestType      trigger.test_type;   XSyncCATestType
 410 XSyncValue         delta;               XSyncCADelta
 411 Bool               events;              XSyncCAEvents
 412 XSyncAlarmState    state;               client cannot set this
 413 </literallayout>
 414
 415 <funcsynopsis>
 416 <funcprototype>
 417   <funcdef>Status <function>XSyncDestroyAlarm</function></funcdef>
 418     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 419     <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>
 420 </funcprototype>
 421 </funcsynopsis>
 422
 423 <para>
 424 <function>XSyncDestroyAlarm</function> destroys alarm. It returns
 425 <function>False</function> if dpy does not support
 426 the SYNC extension; otherwise, it returns <function>True</function>.
 427 </para>
 428
 429 <funcsynopsis>
 430 <funcprototype>
 431   <funcdef>Status <function>XSyncQueryAlarm</function></funcdef>
 432     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 433     <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>
 434     <paramdef>XSyncAlarmAttributes<parameter> *values_return</parameter></paramdef>
 435 </funcprototype>
 436 </funcsynopsis>
 437
 438
 439 <para>
 440 <function>XSyncQueryAlarm</function> sets *values_return to the alarm’s
 441 attributes. It returns <function>False</function> if there was an error
 442 during communication with the server or if dpy does not support the
 443 SYNC extension; otherwise, it returns <function>True</function>.
 444 </para>
 445
 446 <funcsynopsis>
 447 <funcprototype>
 448   <funcdef>Status <function>XSyncChangeAlarm</function></funcdef>
 449     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 450     <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>
 451     <paramdef>unsigned long<parameter> values_mask</parameter></paramdef>
 452     <paramdef>XSyncAlarmAttributes<parameter> *values</parameter></paramdef>
 453 </funcprototype>
 454 </funcsynopsis>
 455
 456 <para>
 457 <function>XSyncChangeAlarm</function> changes alarm’s attributes. The
 458 attributes to change are specified as in
 459 <function>XSyncCreateAlarm</function>. It returns
 460 <function>False</function> if dpy does not support
 461 the SYNC extension; otherwise, it returns <function>True</function>.
 462 </para>
 463
 464 <funcsynopsis>
 465 <funcprototype>
 466   <funcdef>Status <function>XSyncSetPriority</function></funcdef>
 467     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 468     <paramdef>XID<parameter> client_resource_id</parameter></paramdef>
 469     <paramdef>int<parameter> priority</parameter></paramdef>
 470 </funcprototype>
 471 </funcsynopsis>
 472
 473 <para>
 474 <function>XSyncSetPriority</function> sets the priority of the client
 475 owning client_resource_id to priority. If client_resource_id is None, it
 476 sets the caller’s priority. It returns
 477 <function>False</function> if dpy does not support the SYNC extension;
 478 otherwise, it returns <function>True</function>.
 479 </para>
 480
 481 <funcsynopsis>
 482 <funcprototype>
 483   <funcdef>Status <function>XSyncGetPriority</function></funcdef>
 484     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 485     <paramdef>XID<parameter> client_resource_id</parameter></paramdef>
 486     <paramdef>int<parameter> *return_priority</parameter></paramdef>
 487 </funcprototype>
 488 </funcsynopsis>
 489
 490 <para>
 491 <function>XSyncGetPriority</function> sets *return_priority to the
 492 priority of the client owning client_resource_id. If client_resource_id
 493 is None, it sets *return_priority to the caller’s priority. It returns
 494 <function>False</function> if there was an error during communication
 495 with the server or if dpy does not support the SYNC extension; otherwise, it
 496 returns <function>True</function>.
 497 </para>
 498
 499 </sect1>
 500
 501 <sect1 id="c_macros_functions">
 502 <title>C Macros/Functions</title>
 503
 504 <para>
 505 The following procedures manipulate 64-bit values. They are defined both as
 506 macros and as functions. By default, the macro form is used. To use the
 507 function form, #undef the macro name to uncover the function.
 508 </para>
 509
 510 <funcsynopsis>
 511 <funcprototype>
 512   <funcdef>void <function>XSyncIntToValue</function></funcdef>
 513     <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>
 514     <paramdef>int<parameter> i</parameter></paramdef>
 515 </funcprototype>
 516 </funcsynopsis>
 517
 518 <para>
 519 Converts i to an <function>XSyncValue</function> and stores it in *pv.
 520 Performs sign extension (*pv will have the same sign as i.)
 521 </para>
 522
 523 <funcsynopsis>
 524 <funcprototype>
 525   <funcdef>void <function>XSyncIntsToValue</function></funcdef>
 526     <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>
 527     <paramdef>unsigned int<parameter> low</parameter></paramdef>
 528     <paramdef>int<parameter> high</parameter></paramdef>
 529 </funcprototype>
 530 </funcsynopsis>
 531
 532 <para>
 533 Stores low in the low 32 bits of *pv and high in the high 32 bits of *pv.
 534 </para>
 535
 536
 537 <funcsynopsis>
 538 <funcprototype>
 539   <funcdef>Bool <function>XSyncValueGreaterThan</function></funcdef>
 540     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 541     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 542 </funcprototype>
 543 </funcsynopsis>
 544
 545 <para>
 546 Returns <function>True</function> if a is greater than b, else returns
 547 <function>False</function>.
 548 </para>
 549
 550 <funcsynopsis>
 551 <funcprototype>
 552   <funcdef>Bool <function>XSyncValueLessThan</function></funcdef>
 553     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 554     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 555 </funcprototype>
 556 </funcsynopsis>
 557
 558 <para>
 559 Returns <function>True</function> if a is less than b, else returns
 560 <function>False</function>.
 561 </para>
 562
 563
 564 <funcsynopsis>
 565 <funcprototype>
 566   <funcdef>Bool <function>XSyncValueGreaterOrEqual</function></funcdef>
 567     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 568     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 569 </funcprototype>
 570 </funcsynopsis>
 571
 572 <para>
 573 Returns <function>True</function> if a is greater than or equal to b,
 574 else returns <function>False</function>.
 575 </para>
 576
 577 <funcsynopsis>
 578 <funcprototype>
 579   <funcdef>Bool <function>XSyncValueLessOrEqual</function></funcdef>
 580     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 581     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 582 </funcprototype>
 583 </funcsynopsis>
 584
 585 <para>
 586 Returns <function>True</function> if a is less than or equal to b,
 587 else returns <function>False</function>.
 588 </para>
 589
 590 <funcsynopsis>
 591 <funcprototype>
 592   <funcdef>Bool <function>XSyncValueEqual</function></funcdef>
 593     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 594     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 595 </funcprototype>
 596 </funcsynopsis>
 597
 598 <para>
 599 Returns <function>True</function> if a is equal to b,
 600 else returns <function>False</function>.
 601 </para>
 602
 603 <funcsynopsis>
 604 <funcprototype>
 605   <funcdef>Bool <function>XSyncValueIsNegative</function></funcdef>
 606     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 607 </funcprototype>
 608 </funcsynopsis>
 609
 610 <para>
 611 Returns <function>True</function> if v is negative,
 612 else returns <function>False</function>.
 613 </para>
 614
 615 <funcsynopsis>
 616 <funcprototype>
 617   <funcdef>Bool <function>XSyncValueIsZero</function></funcdef>
 618     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 619 </funcprototype>
 620 </funcsynopsis>
 621
 622 <para>
 623 Returns <function>True</function> if v is zero,
 624 else returns <function>False</function>.
 625 </para>
 626
 627 <funcsynopsis>
 628 <funcprototype>
 629   <funcdef>Bool <function>XSyncValueIsPositive</function></funcdef>
 630     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 631 </funcprototype>
 632 </funcsynopsis>
 633
 634 <para>
 635 Returns <function>True</function> if v is positive,
 636 else returns <function>False</function>.
 637 </para>
 638
 639 <funcsynopsis>
 640 <funcprototype>
 641   <funcdef>unsigned int <function>XSyncValueLow32</function></funcdef>
 642     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 643 </funcprototype>
 644 </funcsynopsis>
 645
 646 <para>
 647 Returns the low 32 bits of v.
 648 </para>
 649
 650 <funcsynopsis>
 651 <funcprototype>
 652   <funcdef>unsigned int <function>XSyncValueHigh32</function></funcdef>
 653     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 654 </funcprototype>
 655 </funcsynopsis>
 656
 657 <para>
 658 Returns the high 32 bits of v.
 659 </para>
 660
 661 <funcsynopsis>
 662 <funcprototype>
 663   <funcdef>void <function>XSyncValueAdd</function></funcdef>
 664     <paramdef>XSyncValue<parameter> *presult</parameter></paramdef>
 665     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 666     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 667     <paramdef>Bool<parameter> *poverflow</parameter></paramdef>
 668 </funcprototype>
 669 </funcsynopsis>
 670
 671 <para>
 672 Adds a to b and stores the result in *presult. If the result could not
 673 fit in 64 bits, *poverﬂow is set to <function>True</function>, else it is
 674 set to <function>False</function>.
 675 </para>
 676
 677 <funcsynopsis>
 678 <funcprototype>
 679   <funcdef>void <function>XSyncValueSubtract</function></funcdef>
 680     <paramdef>XSyncValue<parameter> *presult</parameter></paramdef>
 681     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 682     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 683     <paramdef>Bool<parameter> *poverflow</parameter></paramdef>
 684 </funcprototype>
 685 </funcsynopsis>
 686
 687 <para>
 688 Subtracts b from a and stores the result in *presult. If the result could not
 689 fit in 64 bits, *poverﬂow is set to <function>True</function>, else it is
 690 set to <function>False</function>.
 691 </para>
 692
 693 <funcsynopsis>
 694 <funcprototype>
 695   <funcdef>void <function>XSyncMaxValue</function></funcdef>
 696     <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>
 697 </funcprototype>
 698 </funcsynopsis>
 699
 700 <para>
 701 Sets *pv to the maximum value expressible in 64 bits.
 702 </para>
 703
 704 <funcsynopsis>
 705 <funcprototype>
 706   <funcdef>void <function>XSyncMinValue</function></funcdef>
 707     <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>
 708 </funcprototype>
 709 </funcsynopsis>
 710
 711 <para>
 712 Sets *pv to the minimum value expressible in 64 bits.
 713 </para>
 714
 715 </sect1>
 716
 717 <sect1 id="events">
 718 <title>Events</title>
 719
 720 <para>
 721 Let <emphasis remap='I'>event_base</emphasis> be the value event base return as defined in the function
 722 <function>XSyncQueryExtension</function>.
 723 </para>
 724
 725 <para>
 726 An <function>XSyncCounterNotifyEvent</function>’s type field has the value
 727 event_base + <function>XSyncCounterNotify</function>. The fields of this
 728 structure are:
 729 </para>
 730
 731 <literallayout remap='Ds'>
 732 int              type;          /* event base + XSyncCounterNotify */
 733 unsigned long    serial;        /* number of last request processed by server */
 734 Bool             send event;    /* true if this came from a SendEvent request */
 735 Display *        display;       /* Display the event was read from */
 736 XSyncCounter     counter;       /* counter involved in await */
 737 XSyncValue       wait_value;    /* value being waited for */
 738 XSyncValue       counter_value; /* counter value when this event was sent */
 739 Time             time;          /* milliseconds */
 740 int              count;         /* how many more events to come */
 741 Bool             destroyed;     /* True if counter was destroyed */
 742 </literallayout>
 743
 744 <para>
 745 An <function>XSyncAlarmNotifyEvent</function>’s type field has the value
 746 event_base + <function>XSyncAlarmNotify</function>. The fields of
 747 this structure are:
 748 </para>
 749
 750 <literallayout remap='Ds'>
 751 int             type;         /* event_base + XSyncAlarmNotify */
 752 unsigned long   serial;       /* number of last request processed by server */
 753 Bool            send_event;   /* true if this came from a SendEvent request */
 754 Display *       display;      /*Display the event was read from */
 755 XSyncAlarm      alarm;        /* alarm that triggered */
 756 XSyncValue      counter_value /* value that triggered the alarm */
 757 XSyncValue      alarm_value   /* test value of trigger in alarm */
 758 Time            time;         /* milliseconds */
 759 XSyncAlarmState state;        /* new state of alarm */
 760 </literallayout>
 761
 762 </sect1>
 763
 764 <sect1 id="errors">
 765 <title>Errors</title>
 766 <para>
 767 Let <emphasis remap='I'>error_base</emphasis> be the value
 768 <emphasis remap='I'>error_base_return</emphasis> as defined in the function
 769 <function>XSyncQueryExtension</function>.
 770 </para>
 771
 772 <para>
 773 An <function>XSyncAlarmError</function>’s error_code field has
 774 <function>XSyncBadAlarm</function>. The fields of this structure are:
 775 </para>
 776
 777 <literallayout remap='Ds'>
 778 int                type
 779 Display *          display;      /* Display the event was read from */
 780 XSyncCounter       counter;      /* resource id */
 781 unsigned long      serial;       /* serial number of failed request */
 782 unsigned char      error_code;   /* error_base + XSyncBadAlarm */
 783 unsigned char      request_code; /* Major op-code of failed request */
 784 unsigned char      minor_code;   /* Minor op-code of failed request */
 785 </literallayout>
 786
 787 <para>
 788 An <function>XSyncCounterError</function>’s error code field has the value
 789 error_base + <function>XSyncBadCounter</function>. The fields of this
 790 structure are:
 791 </para>
 792 <literallayout remap='Ds'>
 793 int                type
 794 Display *          display;      /* Display the event was read from */
 795 XSyncCounter       counter;      /* resource id */
 796 unsigned long      serial;       /* serial number of failed request */
 797 unsigned char      error_code;   /* error_base + XSyncBadCounter */
 798 unsigned char      request_code; /* Major op-code of failed request */
 799 unsigned char      minor_code;   /* Minor op-code of failed request */
 800 </literallayout>
 801
 802 </sect1>
 803 </chapter>
 804 </book>