← Back to branch summary

~ubuntu-branches/ubuntu/quantal/glib2.0/quantal-updates

« back to all changes in this revision

Viewing changes to docs/reference/glib/html/glib-Threads.html

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2012-09-20 18:05:37 UTC
  • mfrom: (1.63.9) (162.1.6 quantal)
  • Revision ID: package-import@ubuntu.com-20120920180537-ztouhce80mq4z76j
Tags: 2.33.14-1svn1
Upload current Debian packaging svn head.

* debian/rules: Only run tests for the main flavour; it takes too
  long for all three and does not give us a lot of extra confidence.
* Add 07_socket_test_bump_max_time.patch: Increase /socket/timed_wait test
  max time. On slow architectures like armel, this test often fails due to
  "(poll_duration < 110000): (154022 < 110000)".

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/html/glib-Threads.html
3
3
<head>
4
4
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
5
<title>Threads</title>
6
 
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
 
6
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7
7
<link rel="home" href="index.html" title="GLib Reference Manual">
8
8
<link rel="up" href="glib-core.html" title="GLib Core Application Support">
9
9
<link rel="prev" href="glib-The-Main-Event-Loop.html" title="The Main Event Loop">
10
10
<link rel="next" href="glib-Thread-Pools.html" title="Thread Pools">
11
 
<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
 
11
<meta name="generator" content="GTK-Doc V1.18 (XML mode)">
12
12
<link rel="stylesheet" href="style.css" type="text/css">
13
13
</head>
14
14
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
180
180
UNIX APIs are problematic in threaded programs. Some notable examples
181
181
are
182
182
</p>
183
 
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 
183
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
184
184
<li class="listitem">
185
185
    C library functions that return data in statically allocated
186
186
    buffers, such as <code class="function">strtok()</code> or <code class="function">strerror()</code>. For many of these,
228
228
threads. The two notable exceptions from this rule are <a class="link" href="glib-The-Main-Event-Loop.html#GMainLoop" title="GMainLoop"><span class="type">GMainLoop</span></a>
229
229
and <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>, which <span class="emphasis"><em>are</em></span> thread-safe and
230
230
need no further application-level locking to be accessed from
231
 
multiple threads. Most refcounting functions such as <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-ref"><code class="function">g_object_ref()</code></a>
 
231
multiple threads. Most refcounting functions such as <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-ref"><code class="function">g_object_ref()</code></a>
232
232
are also thread-safe.
233
233
</p>
234
234
</div>
252
252
<p>
253
253
Possible errors of thread related functions.
254
254
</p>
255
 
<div class="variablelist"><table border="0" class="variablelist">
256
 
<colgroup>
 
255
<div class="variablelist"><table border="0">
257
256
<col align="left" valign="top">
258
 
<col>
259
 
</colgroup>
260
257
<tbody><tr>
261
258
<td><p><a name="G-THREAD-ERROR-AGAIN:CAPS"></a><span class="term"><code class="literal">G_THREAD_ERROR_AGAIN</code></span></p></td>
262
259
<td>a thread couldn't be created due to resource
297
294
Specifies the type of the <em class="parameter"><code>func</code></em> functions passed to <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()"><code class="function">g_thread_new()</code></a>
298
295
or <a class="link" href="glib-Threads.html#g-thread-try-new" title="g_thread_try_new ()"><code class="function">g_thread_try_new()</code></a>.
299
296
</p>
300
 
<div class="variablelist"><table border="0" class="variablelist">
301
 
<colgroup>
 
297
<div class="variablelist"><table border="0">
302
298
<col align="left" valign="top">
303
 
<col>
304
 
</colgroup>
305
299
<tbody>
306
300
<tr>
307
301
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
339
333
To free the struct returned by this function, use <a class="link" href="glib-Threads.html#g-thread-unref" title="g_thread_unref ()"><code class="function">g_thread_unref()</code></a>.
340
334
Note that <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> implicitly unrefs the <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> as well.
341
335
</p>
342
 
<div class="variablelist"><table border="0" class="variablelist">
343
 
<colgroup>
 
336
<div class="variablelist"><table border="0">
344
337
<col align="left" valign="top">
345
 
<col>
346
 
</colgroup>
347
338
<tbody>
348
339
<tr>
349
340
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
381
372
If a thread can not be created (due to resource limits),
382
373
<em class="parameter"><code>error</code></em> is set and <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
383
374
</p>
384
 
<div class="variablelist"><table border="0" class="variablelist">
385
 
<colgroup>
 
375
<div class="variablelist"><table border="0">
386
376
<col align="left" valign="top">
387
 
<col>
388
 
</colgroup>
389
377
<tbody>
390
378
<tr>
391
379
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
419
407
<p>
420
408
Increase the reference count on <em class="parameter"><code>thread</code></em>.
421
409
</p>
422
 
<div class="variablelist"><table border="0" class="variablelist">
423
 
<colgroup>
 
410
<div class="variablelist"><table border="0">
424
411
<col align="left" valign="top">
425
 
<col>
426
 
</colgroup>
427
412
<tbody>
428
413
<tr>
429
414
<td><p><span class="term"><em class="parameter"><code>thread</code></em> :</span></p></td>
452
437
it is running, so it is safe to drop your own reference to it
453
438
if you don't need it anymore.
454
439
</p>
455
 
<div class="variablelist"><table border="0" class="variablelist">
456
 
<colgroup>
 
440
<div class="variablelist"><table border="0">
457
441
<col align="left" valign="top">
458
 
<col>
459
 
</colgroup>
460
442
<tbody><tr>
461
443
<td><p><span class="term"><em class="parameter"><code>thread</code></em> :</span></p></td>
462
444
<td>a <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a>
490
472
to be freed. Use <a class="link" href="glib-Threads.html#g-thread-ref" title="g_thread_ref ()"><code class="function">g_thread_ref()</code></a> to obtain an extra reference if you
491
473
want to keep the GThread alive beyond the <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> call.
492
474
</p>
493
 
<div class="variablelist"><table border="0" class="variablelist">
494
 
<colgroup>
 
475
<div class="variablelist"><table border="0">
495
476
<col align="left" valign="top">
496
 
<col>
497
 
</colgroup>
498
477
<tbody>
499
478
<tr>
500
479
<td><p><span class="term"><em class="parameter"><code>thread</code></em> :</span></p></td>
549
528
</div>
550
529
<p>
551
530
</p>
552
 
<div class="variablelist"><table border="0" class="variablelist">
553
 
<colgroup>
 
531
<div class="variablelist"><table border="0">
554
532
<col align="left" valign="top">
555
 
<col>
556
 
</colgroup>
557
533
<tbody><tr>
558
534
<td><p><span class="term"><em class="parameter"><code>retval</code></em> :</span></p></td>
559
535
<td>the return value of this thread</td>
576
552
(i.e. comparisons) but you must not use GLib functions (such
577
553
as <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>) on these threads.
578
554
</p>
579
 
<div class="variablelist"><table border="0" class="variablelist">
580
 
<colgroup>
 
555
<div class="variablelist"><table border="0">
581
556
<col align="left" valign="top">
582
 
<col>
583
 
</colgroup>
584
557
<tbody><tr>
585
558
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
586
559
<td>the <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> representing the current thread</td>
605
578
<p>
606
579
</p>
607
580
<div class="example">
608
 
<a name="id655057"></a><p class="title"><b>Example 2. A function which will not work in a threaded environment</b></p>
609
 
<div class="example-contents">
610
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
611
 
    <tbody>
612
 
      <tr>
613
 
        <td class="listing_lines" align="right"><pre>1
614
 
2
615
 
3
616
 
4
617
 
5
618
 
6
619
 
7
620
 
8
621
 
9
622
 
10
623
 
11
624
 
12</pre></td>
625
 
        <td class="listing_code"><pre class="programlisting"><span class="type">int</span>
626
 
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
627
 
<span class="cbracket">{</span>
628
 
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="type">int</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
629
 
 
630
 
<span class="normal">  </span><span class="comment">/* now do a very complicated calculation to calculate the new</span>
631
 
<span class="comment">   * number, this might for example be a random number generator</span>
632
 
<span class="comment">   */</span>
633
 
<span class="normal">  current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
634
 
 
635
 
<span class="normal">  </span><span class="keyword">return</span><span class="normal"> current_number</span><span class="symbol">;</span>
636
 
<span class="cbracket">}</span></pre></td>
637
 
      </tr>
638
 
    </tbody>
639
 
  </table>
640
 
</div>
641
 
 
 
581
<a name="idp17595376"></a><p class="title"><b>Example 2. A function which will not work in a threaded environment</b></p>
 
582
<div class="example-contents"><pre class="programlisting">
 
583
  int
 
584
  give_me_next_number (void)
 
585
  {
 
586
    static int current_number = 0;
 
587
 
 
588
    /* now do a very complicated calculation to calculate the new
 
589
     * number, this might for example be a random number generator
 
590
     */
 
591
    current_number = calc_next_number (current_number);
 
592
 
 
593
    return current_number;
 
594
  }
 
595
 </pre></div>
642
596
</div>
643
597
<p><br class="example-break">
644
598
</p>
650
604
<p>
651
605
</p>
652
606
<div class="example">
653
 
<a name="id655093"></a><p class="title"><b>Example 3. Using GMutex to protected a shared variable</b></p>
654
 
<div class="example-contents">
655
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
656
 
    <tbody>
657
 
      <tr>
658
 
        <td class="listing_lines" align="right"><pre>1
659
 
2
660
 
3
661
 
4
662
 
5
663
 
6
664
 
7
665
 
8
666
 
9
667
 
10
668
 
11
669
 
12
670
 
13</pre></td>
671
 
        <td class="listing_code"><pre class="programlisting"><span class="type">int</span>
672
 
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
673
 
<span class="cbracket">{</span>
674
 
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="usertype">GMutex</span><span class="normal"> mutex</span><span class="symbol">;</span>
675
 
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="type">int</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
676
 
<span class="normal">  </span><span class="type">int</span><span class="normal"> ret_val</span><span class="symbol">;</span>
677
 
 
678
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-lock">g_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">mutex</span><span class="symbol">);</span>
679
 
<span class="normal">  ret_val </span><span class="symbol">=</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
680
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">mutex</span><span class="symbol">);</span>
681
 
 
682
 
<span class="normal">  </span><span class="keyword">return</span><span class="normal"> ret_val</span><span class="symbol">;</span>
683
 
<span class="cbracket">}</span></pre></td>
684
 
      </tr>
685
 
    </tbody>
686
 
  </table>
687
 
</div>
688
 
 
 
607
<a name="idp17599680"></a><p class="title"><b>Example 3. Using GMutex to protected a shared variable</b></p>
 
608
<div class="example-contents"><pre class="programlisting">
 
609
  int
 
610
  give_me_next_number (void)
 
611
  {
 
612
    static GMutex mutex;
 
613
    static int current_number = 0;
 
614
    int ret_val;
 
615
 
 
616
    g_mutex_lock (&amp;mutex);
 
617
    ret_val = current_number = calc_next_number (current_number);
 
618
    g_mutex_unlock (&amp;mutex);
 
619
 
 
620
    return ret_val;
 
621
  }
 
622
 </pre></div>
689
623
</div>
690
624
<p><br class="example-break">
691
625
</p>
718
652
</p>
719
653
<p>
720
654
</p>
721
 
<div class="informalexample">
722
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
723
 
    <tbody>
724
 
      <tr>
725
 
        <td class="listing_lines" align="right"><pre>1
726
 
2
727
 
3
728
 
4
729
 
5
730
 
6
731
 
7
732
 
8
733
 
9</pre></td>
734
 
        <td class="listing_code"><pre class="programlisting"><span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="cbracket">{</span>
735
 
<span class="normal">  </span><span class="usertype">GMutex</span><span class="normal"> m</span><span class="symbol">;</span>
736
 
<span class="normal">  </span><span class="symbol">...</span>
737
 
<span class="cbracket">}</span><span class="normal"> Blob</span><span class="symbol">;</span>
738
 
 
739
 
<span class="usertype">Blob</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">b</span><span class="symbol">;</span>
740
 
 
741
 
<span class="normal">b </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Memory-Allocation.html#g-new">g_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">Blob</span><span class="symbol">,</span><span class="normal"> </span><span class="number">1</span><span class="symbol">);</span>
742
 
<span class="function"><a href="glib-Threads.html#g-mutex-init">g_mutex_init</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">b</span><span class="symbol">-&gt;</span><span class="normal">m</span><span class="symbol">);</span></pre></td>
743
 
      </tr>
744
 
    </tbody>
745
 
  </table>
746
 
</div>
747
 
 
 
655
<div class="informalexample"><pre class="programlisting">
 
656
  typedef struct {
 
657
    GMutex m;
 
658
    ...
 
659
  } Blob;
 
660
 
 
661
Blob *b;
 
662
 
 
663
b = g_new (Blob, 1);
 
664
g_mutex_init (&amp;b-&gt;m);
 
665
</pre></div>
748
666
<p>
749
667
</p>
750
668
<p>
755
673
Calling <a class="link" href="glib-Threads.html#g-mutex-init" title="g_mutex_init ()"><code class="function">g_mutex_init()</code></a> on an already initialized <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> leads
756
674
to undefined behaviour.
757
675
</p>
758
 
<div class="variablelist"><table border="0" class="variablelist">
759
 
<colgroup>
 
676
<div class="variablelist"><table border="0">
760
677
<col align="left" valign="top">
761
 
<col>
762
 
</colgroup>
763
678
<tbody><tr>
764
679
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
765
680
<td>an uninitialized <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
786
701
<p>
787
702
Sine: 2.32
788
703
</p>
789
 
<div class="variablelist"><table border="0" class="variablelist">
790
 
<colgroup>
 
704
<div class="variablelist"><table border="0">
791
705
<col align="left" valign="top">
792
 
<col>
793
 
</colgroup>
794
706
<tbody><tr>
795
707
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
796
708
<td>an initialized <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
817
729
(including but not limited to deadlocks).</div>
818
730
<p>
819
731
</p>
820
 
<div class="variablelist"><table border="0" class="variablelist">
821
 
<colgroup>
 
732
<div class="variablelist"><table border="0">
822
733
<col align="left" valign="top">
823
 
<col>
824
 
</colgroup>
825
734
<tbody><tr>
826
735
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
827
736
<td>a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
849
758
</div>
850
759
<p>
851
760
</p>
852
 
<div class="variablelist"><table border="0" class="variablelist">
853
 
<colgroup>
 
761
<div class="variablelist"><table border="0">
854
762
<col align="left" valign="top">
855
 
<col>
856
 
</colgroup>
857
763
<tbody>
858
764
<tr>
859
765
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
880
786
Calling <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()"><code class="function">g_mutex_unlock()</code></a> on a mutex that is not locked by the
881
787
current thread leads to undefined behaviour.
882
788
</p>
883
 
<div class="variablelist"><table border="0" class="variablelist">
884
 
<colgroup>
 
789
<div class="variablelist"><table border="0">
885
790
<col align="left" valign="top">
886
 
<col>
887
 
</colgroup>
888
791
<tbody><tr>
889
792
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
890
793
<td>a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
911
814
<p>
912
815
</p>
913
816
<div class="example">
914
 
<a name="id655947"></a><p class="title"><b>Example 4. Using the <code class="literal">G_LOCK_*</code> convenience macros</b></p>
915
 
<div class="example-contents">
916
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
917
 
    <tbody>
918
 
      <tr>
919
 
        <td class="listing_lines" align="right"><pre>1
920
 
2
921
 
3
922
 
4
923
 
5
924
 
6
925
 
7
926
 
8
927
 
9
928
 
10
929
 
11
930
 
12
931
 
13
932
 
14</pre></td>
933
 
        <td class="listing_code"><pre class="programlisting"><span class="function"><a href="glib-Threads.html#G-LOCK-DEFINE:CAPS">G_LOCK_DEFINE</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
934
 
 
935
 
<span class="type">int</span>
936
 
<span class="function">give_me_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
937
 
<span class="cbracket">{</span>
938
 
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="type">int</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
939
 
<span class="normal">  </span><span class="type">int</span><span class="normal"> ret_val</span><span class="symbol">;</span>
940
 
 
941
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#G-LOCK:CAPS">G_LOCK</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
942
 
<span class="normal">  ret_val </span><span class="symbol">=</span><span class="normal"> current_number </span><span class="symbol">=</span><span class="normal"> </span><span class="function">calc_next_number</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
943
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#G-UNLOCK:CAPS">G_UNLOCK</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">current_number</span><span class="symbol">);</span>
944
 
 
945
 
<span class="normal">  </span><span class="keyword">return</span><span class="normal"> ret_val</span><span class="symbol">;</span>
946
 
<span class="cbracket">}</span></pre></td>
947
 
      </tr>
948
 
    </tbody>
949
 
  </table>
950
 
</div>
951
 
 
 
817
<a name="idp17702016"></a><p class="title"><b>Example 4. Using the <code class="literal">G_LOCK_*</code> convenience macros</b></p>
 
818
<div class="example-contents"><pre class="programlisting">
 
819
  G_LOCK_DEFINE (current_number);
 
820
 
 
821
  int
 
822
  give_me_next_number (void)
 
823
  {
 
824
    static int current_number = 0;
 
825
    int ret_val;
 
826
 
 
827
    G_LOCK (current_number);
 
828
    ret_val = current_number = calc_next_number (current_number);
 
829
    G_UNLOCK (current_number);
 
830
 
 
831
    return ret_val;
 
832
  }
 
833
 </pre></div>
952
834
</div>
953
835
<p><br class="example-break">
954
836
</p>
955
 
<div class="variablelist"><table border="0" class="variablelist">
956
 
<colgroup>
 
837
<div class="variablelist"><table border="0">
957
838
<col align="left" valign="top">
958
 
<col>
959
 
</colgroup>
960
839
<tbody><tr>
961
840
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
962
841
<td>the name of the lock</td>
971
850
<p>
972
851
This works like <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>, but it creates a static object.
973
852
</p>
974
 
<div class="variablelist"><table border="0" class="variablelist">
975
 
<colgroup>
 
853
<div class="variablelist"><table border="0">
976
854
<col align="left" valign="top">
977
 
<col>
978
 
</colgroup>
979
855
<tbody><tr>
980
856
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
981
857
<td>the name of the lock</td>
991
867
This declares a lock, that is defined with <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a> in another
992
868
module.
993
869
</p>
994
 
<div class="variablelist"><table border="0" class="variablelist">
995
 
<colgroup>
 
870
<div class="variablelist"><table border="0">
996
871
<col align="left" valign="top">
997
 
<col>
998
 
</colgroup>
999
872
<tbody><tr>
1000
873
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
1001
874
<td>the name of the lock</td>
1011
884
Works like <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a>, but for a lock defined with
1012
885
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
1013
886
</p>
1014
 
<div class="variablelist"><table border="0" class="variablelist">
1015
 
<colgroup>
 
887
<div class="variablelist"><table border="0">
1016
888
<col align="left" valign="top">
1017
 
<col>
1018
 
</colgroup>
1019
889
<tbody><tr>
1020
890
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
1021
891
<td>the name of the lock</td>
1031
901
Works like <a class="link" href="glib-Threads.html#g-mutex-trylock" title="g_mutex_trylock ()"><code class="function">g_mutex_trylock()</code></a>, but for a lock defined with
1032
902
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
1033
903
</p>
1034
 
<div class="variablelist"><table border="0" class="variablelist">
1035
 
<colgroup>
 
904
<div class="variablelist"><table border="0">
1036
905
<col align="left" valign="top">
1037
 
<col>
1038
 
</colgroup>
1039
906
<tbody>
1040
907
<tr>
1041
908
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
1058
925
Works like <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()"><code class="function">g_mutex_unlock()</code></a>, but for a lock defined with
1059
926
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
1060
927
</p>
1061
 
<div class="variablelist"><table border="0" class="variablelist">
1062
 
<colgroup>
 
928
<div class="variablelist"><table border="0">
1063
929
<col align="left" valign="top">
1064
 
<col>
1065
 
</colgroup>
1066
930
<tbody><tr>
1067
931
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
1068
932
<td>the name of the lock</td>
1111
975
</p>
1112
976
<p>
1113
977
</p>
1114
 
<div class="informalexample">
1115
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
1116
 
    <tbody>
1117
 
      <tr>
1118
 
        <td class="listing_lines" align="right"><pre>1
1119
 
2
1120
 
3
1121
 
4
1122
 
5
1123
 
6
1124
 
7
1125
 
8
1126
 
9</pre></td>
1127
 
        <td class="listing_code"><pre class="programlisting"><span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="cbracket">{</span>
1128
 
<span class="normal">  </span><span class="usertype">GRecMutex</span><span class="normal"> m</span><span class="symbol">;</span>
1129
 
<span class="normal">  </span><span class="symbol">...</span>
1130
 
<span class="cbracket">}</span><span class="normal"> Blob</span><span class="symbol">;</span>
1131
 
 
1132
 
<span class="usertype">Blob</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">b</span><span class="symbol">;</span>
1133
 
 
1134
 
<span class="normal">b </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Memory-Allocation.html#g-new">g_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">Blob</span><span class="symbol">,</span><span class="normal"> </span><span class="number">1</span><span class="symbol">);</span>
1135
 
<span class="function"><a href="glib-Threads.html#g-rec-mutex-init">g_rec_mutex_init</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">b</span><span class="symbol">-&gt;</span><span class="normal">m</span><span class="symbol">);</span></pre></td>
1136
 
      </tr>
1137
 
    </tbody>
1138
 
  </table>
1139
 
</div>
1140
 
 
 
978
<div class="informalexample"><pre class="programlisting">
 
979
  typedef struct {
 
980
    GRecMutex m;
 
981
    ...
 
982
  } Blob;
 
983
 
 
984
Blob *b;
 
985
 
 
986
b = g_new (Blob, 1);
 
987
g_rec_mutex_init (&amp;b-&gt;m);
 
988
</pre></div>
1141
989
<p>
1142
990
</p>
1143
991
<p>
1148
996
To undo the effect of <a class="link" href="glib-Threads.html#g-rec-mutex-init" title="g_rec_mutex_init ()"><code class="function">g_rec_mutex_init()</code></a> when a recursive mutex
1149
997
is no longer needed, use <a class="link" href="glib-Threads.html#g-rec-mutex-clear" title="g_rec_mutex_clear ()"><code class="function">g_rec_mutex_clear()</code></a>.
1150
998
</p>
1151
 
<div class="variablelist"><table border="0" class="variablelist">
1152
 
<colgroup>
 
999
<div class="variablelist"><table border="0">
1153
1000
<col align="left" valign="top">
1154
 
<col>
1155
 
</colgroup>
1156
1001
<tbody><tr>
1157
1002
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
1158
1003
<td>an uninitialized <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
1180
1025
<p>
1181
1026
Sine: 2.32
1182
1027
</p>
1183
 
<div class="variablelist"><table border="0" class="variablelist">
1184
 
<colgroup>
 
1028
<div class="variablelist"><table border="0">
1185
1029
<col align="left" valign="top">
1186
 
<col>
1187
 
</colgroup>
1188
1030
<tbody><tr>
1189
1031
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
1190
1032
<td>an initialized <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
1204
1046
The mutex will only become available again when it is unlocked
1205
1047
as many times as it has been locked.
1206
1048
</p>
1207
 
<div class="variablelist"><table border="0" class="variablelist">
1208
 
<colgroup>
 
1049
<div class="variablelist"><table border="0">
1209
1050
<col align="left" valign="top">
1210
 
<col>
1211
 
</colgroup>
1212
1051
<tbody><tr>
1213
1052
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
1214
1053
<td>a <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
1226
1065
by another thread, it immediately returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>. Otherwise
1227
1066
it locks <em class="parameter"><code>rec_mutex</code></em> and returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
1228
1067
</p>
1229
 
<div class="variablelist"><table border="0" class="variablelist">
1230
 
<colgroup>
 
1068
<div class="variablelist"><table border="0">
1231
1069
<col align="left" valign="top">
1232
 
<col>
1233
 
</colgroup>
1234
1070
<tbody>
1235
1071
<tr>
1236
1072
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
1259
1095
Calling <a class="link" href="glib-Threads.html#g-rec-mutex-unlock" title="g_rec_mutex_unlock ()"><code class="function">g_rec_mutex_unlock()</code></a> on a recursive mutex that is not
1260
1096
locked by the current thread leads to undefined behaviour.
1261
1097
</p>
1262
 
<div class="variablelist"><table border="0" class="variablelist">
1263
 
<colgroup>
 
1098
<div class="variablelist"><table border="0">
1264
1099
<col align="left" valign="top">
1265
 
<col>
1266
 
</colgroup>
1267
1100
<tbody><tr>
1268
1101
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
1269
1102
<td>a <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
1294
1127
<p>
1295
1128
</p>
1296
1129
<div class="example">
1297
 
<a name="id652467"></a><p class="title"><b>Example 5. An array with access functions</b></p>
 
1130
<a name="idp17851024"></a><p class="title"><b>Example 5. An array with access functions</b></p>
1298
1131
<div class="example-contents">
1299
1132
<pre class="programlisting">
1300
1133
  GRWLock lock;
1370
1203
</p>
1371
1204
<p>
1372
1205
</p>
1373
 
<div class="informalexample">
1374
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
1375
 
    <tbody>
1376
 
      <tr>
1377
 
        <td class="listing_lines" align="right"><pre>1
1378
 
2
1379
 
3
1380
 
4
1381
 
5
1382
 
6
1383
 
7
1384
 
8
1385
 
9</pre></td>
1386
 
        <td class="listing_code"><pre class="programlisting"><span class="keyword">typedef</span><span class="normal"> </span><span class="keyword">struct</span><span class="normal"> </span><span class="cbracket">{</span>
1387
 
<span class="normal">  </span><span class="usertype">GRWLock</span><span class="normal"> l</span><span class="symbol">;</span>
1388
 
<span class="normal">  </span><span class="symbol">...</span>
1389
 
<span class="cbracket">}</span><span class="normal"> Blob</span><span class="symbol">;</span>
1390
 
 
1391
 
<span class="usertype">Blob</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">b</span><span class="symbol">;</span>
1392
 
 
1393
 
<span class="normal">b </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Memory-Allocation.html#g-new">g_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">Blob</span><span class="symbol">,</span><span class="normal"> </span><span class="number">1</span><span class="symbol">);</span>
1394
 
<span class="function"><a href="glib-Threads.html#g-rw-lock-init">g_rw_lock_init</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">b</span><span class="symbol">-&gt;</span><span class="normal">l</span><span class="symbol">);</span></pre></td>
1395
 
      </tr>
1396
 
    </tbody>
1397
 
  </table>
1398
 
</div>
1399
 
 
 
1206
<div class="informalexample"><pre class="programlisting">
 
1207
  typedef struct {
 
1208
    GRWLock l;
 
1209
    ...
 
1210
  } Blob;
 
1211
 
 
1212
Blob *b;
 
1213
 
 
1214
b = g_new (Blob, 1);
 
1215
g_rw_lock_init (&amp;b-&gt;l);
 
1216
</pre></div>
1400
1217
<p>
1401
1218
</p>
1402
1219
<p>
1407
1224
Calling <a class="link" href="glib-Threads.html#g-rw-lock-init" title="g_rw_lock_init ()"><code class="function">g_rw_lock_init()</code></a> on an already initialized <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> leads
1408
1225
to undefined behaviour.
1409
1226
</p>
1410
 
<div class="variablelist"><table border="0" class="variablelist">
1411
 
<colgroup>
 
1227
<div class="variablelist"><table border="0">
1412
1228
<col align="left" valign="top">
1413
 
<col>
1414
 
</colgroup>
1415
1229
<tbody><tr>
1416
1230
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
1417
1231
<td>an uninitialized <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
1438
1252
<p>
1439
1253
Sine: 2.32
1440
1254
</p>
1441
 
<div class="variablelist"><table border="0" class="variablelist">
1442
 
<colgroup>
 
1255
<div class="variablelist"><table border="0">
1443
1256
<col align="left" valign="top">
1444
 
<col>
1445
 
</colgroup>
1446
1257
<tbody><tr>
1447
1258
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
1448
1259
<td>an initialized <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
1459
1270
a read or write lock on <em class="parameter"><code>rw_lock</code></em>, the current thread will block
1460
1271
until all other threads have dropped their locks on <em class="parameter"><code>rw_lock</code></em>.
1461
1272
</p>
1462
 
<div class="variablelist"><table border="0" class="variablelist">
1463
 
<colgroup>
 
1273
<div class="variablelist"><table border="0">
1464
1274
<col align="left" valign="top">
1465
 
<col>
1466
 
</colgroup>
1467
1275
<tbody><tr>
1468
1276
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
1469
1277
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
1481
1289
a read or write lock on <em class="parameter"><code>rw_lock</code></em>, it immediately returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>.
1482
1290
Otherwise it locks <em class="parameter"><code>rw_lock</code></em> and returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
1483
1291
</p>
1484
 
<div class="variablelist"><table border="0" class="variablelist">
1485
 
<colgroup>
 
1292
<div class="variablelist"><table border="0">
1486
1293
<col align="left" valign="top">
1487
 
<col>
1488
 
</colgroup>
1489
1294
<tbody>
1490
1295
<tr>
1491
1296
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
1512
1317
Calling <a class="link" href="glib-Threads.html#g-rw-lock-writer-unlock" title="g_rw_lock_writer_unlock ()"><code class="function">g_rw_lock_writer_unlock()</code></a> on a lock that is not held
1513
1318
by the current thread leads to undefined behaviour.
1514
1319
</p>
1515
 
<div class="variablelist"><table border="0" class="variablelist">
1516
 
<colgroup>
 
1320
<div class="variablelist"><table border="0">
1517
1321
<col align="left" valign="top">
1518
 
<col>
1519
 
</colgroup>
1520
1322
<tbody><tr>
1521
1323
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
1522
1324
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
1538
1340
It is implementation-defined how many threads are allowed to
1539
1341
hold read locks on the same lock simultaneously.
1540
1342
</p>
1541
 
<div class="variablelist"><table border="0" class="variablelist">
1542
 
<colgroup>
 
1343
<div class="variablelist"><table border="0">
1543
1344
<col align="left" valign="top">
1544
 
<col>
1545
 
</colgroup>
1546
1345
<tbody><tr>
1547
1346
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
1548
1347
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
1560
1359
the read lock was successfully obtained. Otherwise it
1561
1360
returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>.
1562
1361
</p>
1563
 
<div class="variablelist"><table border="0" class="variablelist">
1564
 
<colgroup>
 
1362
<div class="variablelist"><table border="0">
1565
1363
<col align="left" valign="top">
1566
 
<col>
1567
 
</colgroup>
1568
1364
<tbody>
1569
1365
<tr>
1570
1366
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
1591
1387
Calling <a class="link" href="glib-Threads.html#g-rw-lock-reader-unlock" title="g_rw_lock_reader_unlock ()"><code class="function">g_rw_lock_reader_unlock()</code></a> on a lock that is not held
1592
1388
by the current thread leads to undefined behaviour.
1593
1389
</p>
1594
 
<div class="variablelist"><table border="0" class="variablelist">
1595
 
<colgroup>
 
1390
<div class="variablelist"><table border="0">
1596
1391
<col align="left" valign="top">
1597
 
<col>
1598
 
</colgroup>
1599
1392
<tbody><tr>
1600
1393
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
1601
1394
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
1626
1419
<p>
1627
1420
</p>
1628
1421
<div class="example">
1629
 
<a name="id653620"></a><p class="title"><b>Example 6. 
 
1422
<a name="idp20484704"></a><p class="title"><b>Example 6. 
1630
1423
  Using GCond to block a thread until a condition is satisfied
1631
1424
 </b></p>
1632
 
<div class="example-contents">
1633
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
1634
 
    <tbody>
1635
 
      <tr>
1636
 
        <td class="listing_lines" align="right"><pre>1
1637
 
2
1638
 
3
1639
 
4
1640
 
5
1641
 
6
1642
 
7
1643
 
8
1644
 
9
1645
 
10
1646
 
11
1647
 
12
1648
 
13
1649
 
14
1650
 
15
1651
 
16
1652
 
17
1653
 
18
1654
 
19
1655
 
20
1656
 
21
1657
 
22
1658
 
23
1659
 
24
1660
 
25
1661
 
26
1662
 
27</pre></td>
1663
 
        <td class="listing_code"><pre class="programlisting"><span class="usertype">gpointer</span><span class="normal"> current_data </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
1664
 
<span class="usertype">GMutex</span><span class="normal"> data_mutex</span><span class="symbol">;</span>
1665
 
<span class="usertype">GCond</span><span class="normal"> data_cond</span><span class="symbol">;</span>
1666
 
 
1667
 
<span class="type">void</span>
1668
 
<span class="function">push_data</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">)</span>
1669
 
<span class="cbracket">{</span>
1670
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-lock">g_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_mutex</span><span class="symbol">);</span>
1671
 
<span class="normal">  current_data </span><span class="symbol">=</span><span class="normal"> data</span><span class="symbol">;</span>
1672
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-cond-signal">g_cond_signal</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_cond</span><span class="symbol">);</span>
1673
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_mutex</span><span class="symbol">);</span>
1674
 
<span class="cbracket">}</span>
1675
 
 
1676
 
<span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span>
1677
 
<span class="function">pop_data</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
1678
 
<span class="cbracket">{</span>
1679
 
<span class="normal">  </span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">;</span>
1680
 
 
1681
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-lock">g_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_mutex</span><span class="symbol">);</span>
1682
 
<span class="normal">  </span><span class="keyword">while</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">current_data</span><span class="symbol">)</span>
1683
 
<span class="normal">    </span><span class="function"><a href="glib-Threads.html#g-cond-wait">g_cond_wait</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_cond</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">data_mutex</span><span class="symbol">);</span>
1684
 
<span class="normal">  data </span><span class="symbol">=</span><span class="normal"> current_data</span><span class="symbol">;</span>
1685
 
<span class="normal">  current_data </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
1686
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_mutex</span><span class="symbol">);</span>
1687
 
 
1688
 
<span class="normal">  </span><span class="keyword">return</span><span class="normal"> data</span><span class="symbol">;</span>
1689
 
<span class="cbracket">}</span></pre></td>
1690
 
      </tr>
1691
 
    </tbody>
1692
 
  </table>
1693
 
</div>
1694
 
 
 
1425
<div class="example-contents"><pre class="programlisting">
 
1426
  gpointer current_data = NULL;
 
1427
  GMutex data_mutex;
 
1428
  GCond data_cond;
 
1429
 
 
1430
  void
 
1431
  push_data (gpointer data)
 
1432
  {
 
1433
    g_mutex_lock (&amp;data_mutex);
 
1434
    current_data = data;
 
1435
    g_cond_signal (&amp;data_cond);
 
1436
    g_mutex_unlock (&amp;data_mutex);
 
1437
  }
 
1438
 
 
1439
  gpointer
 
1440
  pop_data (void)
 
1441
  {
 
1442
    gpointer data;
 
1443
 
 
1444
    g_mutex_lock (&amp;data_mutex);
 
1445
    while (!current_data)
 
1446
      g_cond_wait (&amp;data_cond, &amp;data_mutex);
 
1447
    data = current_data;
 
1448
    current_data = NULL;
 
1449
    g_mutex_unlock (&amp;data_mutex);
 
1450
 
 
1451
    return data;
 
1452
  }
 
1453
 </pre></div>
1695
1454
</div>
1696
1455
<p><br class="example-break">
1697
1456
</p>
1746
1505
Calling <a class="link" href="glib-Threads.html#g-cond-init" title="g_cond_init ()"><code class="function">g_cond_init()</code></a> on an already-initialised <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> leads
1747
1506
to undefined behaviour.
1748
1507
</p>
1749
 
<div class="variablelist"><table border="0" class="variablelist">
1750
 
<colgroup>
 
1508
<div class="variablelist"><table border="0">
1751
1509
<col align="left" valign="top">
1752
 
<col>
1753
 
</colgroup>
1754
1510
<tbody><tr>
1755
1511
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
1756
1512
<td>an uninitialized <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
1774
1530
Calling <a class="link" href="glib-Threads.html#g-cond-clear" title="g_cond_clear ()"><code class="function">g_cond_clear()</code></a> for a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> on which threads are
1775
1531
blocking leads to undefined behaviour.
1776
1532
</p>
1777
 
<div class="variablelist"><table border="0" class="variablelist">
1778
 
<colgroup>
 
1533
<div class="variablelist"><table border="0">
1779
1534
<col align="left" valign="top">
1780
 
<col>
1781
 
</colgroup>
1782
1535
<tbody><tr>
1783
1536
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
1784
1537
<td>an initialised <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
1808
1561
For this reason, <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a> must always be used in a loop.  See
1809
1562
the documentation for <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> for a complete example.
1810
1563
</p>
1811
 
<div class="variablelist"><table border="0" class="variablelist">
1812
 
<colgroup>
 
1564
<div class="variablelist"><table border="0">
1813
1565
<col align="left" valign="top">
1814
 
<col>
1815
 
</colgroup>
1816
1566
<tbody>
1817
1567
<tr>
1818
1568
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
1852
1602
To easily calculate <em class="parameter"><code>abs_time</code></em> a combination of <a class="link" href="glib-Date-and-Time-Functions.html#g-get-current-time" title="g_get_current_time ()"><code class="function">g_get_current_time()</code></a>
1853
1603
and <a class="link" href="glib-Date-and-Time-Functions.html#g-time-val-add" title="g_time_val_add ()"><code class="function">g_time_val_add()</code></a> can be used.
1854
1604
</p>
1855
 
<div class="variablelist"><table border="0" class="variablelist">
1856
 
<colgroup>
 
1605
<div class="variablelist"><table border="0">
1857
1606
<col align="left" valign="top">
1858
 
<col>
1859
 
</colgroup>
1860
1607
<tbody>
1861
1608
<tr>
1862
1609
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
1905
1652
</p>
1906
1653
<p>
1907
1654
</p>
1908
 
<div class="informalexample">
1909
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
1910
 
    <tbody>
1911
 
      <tr>
1912
 
        <td class="listing_lines" align="right"><pre>1
1913
 
2
1914
 
3
1915
 
4
1916
 
5
1917
 
6
1918
 
7
1919
 
8
1920
 
9
1921
 
10
1922
 
11
1923
 
12
1924
 
13
1925
 
14
1926
 
15
1927
 
16
1928
 
17
1929
 
18
1930
 
19
1931
 
20
1932
 
21
1933
 
22
1934
 
23
1935
 
24
1936
 
25</pre></td>
1937
 
        <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span>
1938
 
<span class="function">pop_data_timed</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
1939
 
<span class="cbracket">{</span>
1940
 
<span class="normal">  </span><span class="usertype">gint64</span><span class="normal"> end_time</span><span class="symbol">;</span>
1941
 
<span class="normal">  </span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">;</span>
1942
 
 
1943
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-lock">g_mutex_lock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_mutex</span><span class="symbol">);</span>
1944
 
 
1945
 
<span class="normal">  end_time </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Date-and-Time-Functions.html#g-get-monotonic-time">g_get_monotonic_time</a></span><span class="normal"> </span><span class="symbol">()</span><span class="normal"> </span><span class="symbol">+</span><span class="normal"> </span><span class="number">5</span><span class="normal"> </span><span class="symbol">*</span><span class="normal"> <a href="glib-GDateTime.html#G-TIME-SPAN-SECOND:CAPS">G_TIME_SPAN_SECOND</a></span><span class="symbol">;</span>
1946
 
<span class="normal">  </span><span class="keyword">while</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">current_data</span><span class="symbol">)</span>
1947
 
<span class="normal">    </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function"><a href="glib-Threads.html#g-cond-wait-until">g_cond_wait_until</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_cond</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">data_mutex</span><span class="symbol">,</span><span class="normal"> end_time</span><span class="symbol">))</span>
1948
 
<span class="normal">      </span><span class="cbracket">{</span>
1949
 
<span class="normal">        </span><span class="comment">// timeout has passed.</span>
1950
 
<span class="normal">        </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_mutex</span><span class="symbol">);</span>
1951
 
<span class="normal">        </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
1952
 
<span class="normal">      </span><span class="cbracket">}</span>
1953
 
 
1954
 
<span class="normal">  </span><span class="comment">// there is data for us</span>
1955
 
<span class="normal">  data </span><span class="symbol">=</span><span class="normal"> current_data</span><span class="symbol">;</span>
1956
 
<span class="normal">  current_data </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
1957
 
 
1958
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-mutex-unlock">g_mutex_unlock</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">data_mutex</span><span class="symbol">);</span>
1959
 
 
1960
 
<span class="normal">  </span><span class="keyword">return</span><span class="normal"> data</span><span class="symbol">;</span>
1961
 
<span class="cbracket">}</span></pre></td>
1962
 
      </tr>
1963
 
    </tbody>
1964
 
  </table>
1965
 
</div>
1966
 
 
 
1655
<div class="informalexample"><pre class="programlisting">
 
1656
gpointer
 
1657
pop_data_timed (void)
 
1658
{
 
1659
  gint64 end_time;
 
1660
  gpointer data;
 
1661
 
 
1662
  g_mutex_lock (&amp;data_mutex);
 
1663
 
 
1664
  end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
 
1665
  while (!current_data)
 
1666
    if (!g_cond_wait_until (&amp;data_cond, &amp;data_mutex, end_time))
 
1667
      {
 
1668
        // timeout has passed.
 
1669
        g_mutex_unlock (&amp;data_mutex);
 
1670
        return NULL;
 
1671
      }
 
1672
 
 
1673
  // there is data for us
 
1674
  data = current_data;
 
1675
  current_data = NULL;
 
1676
 
 
1677
  g_mutex_unlock (&amp;data_mutex);
 
1678
 
 
1679
  return data;
 
1680
}
 
1681
</pre></div>
1967
1682
<p>
1968
1683
</p>
1969
1684
<p>
1974
1689
have to start over waiting again (which would lead to a total wait
1975
1690
time of more than 5 seconds).
1976
1691
</p>
1977
 
<div class="variablelist"><table border="0" class="variablelist">
1978
 
<colgroup>
 
1692
<div class="variablelist"><table border="0">
1979
1693
<col align="left" valign="top">
1980
 
<col>
1981
 
</colgroup>
1982
1694
<tbody>
1983
1695
<tr>
1984
1696
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
2012
1724
It is good practice to hold the same lock as the waiting thread
2013
1725
while calling this function, though not required.
2014
1726
</p>
2015
 
<div class="variablelist"><table border="0" class="variablelist">
2016
 
<colgroup>
 
1727
<div class="variablelist"><table border="0">
2017
1728
<col align="left" valign="top">
2018
 
<col>
2019
 
</colgroup>
2020
1729
<tbody><tr>
2021
1730
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
2022
1731
<td>a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
2034
1743
It is good practice to lock the same mutex as the waiting threads
2035
1744
while calling this function, though not required.
2036
1745
</p>
2037
 
<div class="variablelist"><table border="0" class="variablelist">
2038
 
<colgroup>
 
1746
<div class="variablelist"><table border="0">
2039
1747
<col align="left" valign="top">
2040
 
<col>
2041
 
</colgroup>
2042
1748
<tbody><tr>
2043
1749
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
2044
1750
<td>a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
2102
1808
</p>
2103
1809
<p>
2104
1810
</p>
2105
 
<div class="informalexample">
2106
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
2107
 
    <tbody>
2108
 
      <tr>
2109
 
        <td class="listing_lines" align="right"><pre>1
2110
 
2
2111
 
3
2112
 
4
2113
 
5
2114
 
6
2115
 
7
2116
 
8
2117
 
9
2118
 
10
2119
 
11
2120
 
12
2121
 
13
2122
 
14
2123
 
15
2124
 
16
2125
 
17
2126
 
18
2127
 
19
2128
 
20
2129
 
21
2130
 
22
2131
 
23
2132
 
24
2133
 
25
2134
 
26
2135
 
27
2136
 
28
2137
 
29</pre></td>
2138
 
        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="usertype">GPrivate</span><span class="normal"> name_key </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Threads.html#G-PRIVATE-INIT:CAPS">G_PRIVATE_INIT</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Memory-Allocation.html#g-free">g_free</a></span><span class="symbol">);</span>
2139
 
 
2140
 
<span class="comment">// return value should not be freed</span>
2141
 
<span class="keyword">const</span><span class="normal"> <a href="glib-Basic-Types.html#gchar">gchar</a> </span><span class="symbol">*</span>
2142
 
<span class="function">get_local_name</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
2143
 
<span class="cbracket">{</span>
2144
 
<span class="normal">  </span><span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="glib-Threads.html#g-private-get">g_private_get</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">name_key</span><span class="symbol">);</span>
2145
 
<span class="cbracket">}</span>
2146
 
 
2147
 
<span class="type">void</span>
2148
 
<span class="function">set_local_name</span><span class="normal"> </span><span class="symbol">(</span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">name</span><span class="symbol">)</span>
2149
 
<span class="cbracket">{</span>
2150
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-private-replace">g_private_replace</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">name_key</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="glib-String-Utility-Functions.html#g-strdup">g_strdup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">name</span><span class="symbol">));</span>
2151
 
<span class="cbracket">}</span>
2152
 
 
2153
 
 
2154
 
<span class="keyword">static</span><span class="normal"> </span><span class="usertype">GPrivate</span><span class="normal"> count_key</span><span class="symbol">;</span><span class="normal">   </span><span class="comment">// no free function</span>
2155
 
 
2156
 
<span class="normal"><a href="glib-Basic-Types.html#gint">gint</a></span>
2157
 
<span class="function">get_local_count</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
2158
 
<span class="cbracket">{</span>
2159
 
<span class="normal">  </span><span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="glib-Type-Conversion-Macros.html#GPOINTER-TO-INT:CAPS">GPOINTER_TO_INT</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="glib-Threads.html#g-private-get">g_private_get</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">count_key</span><span class="symbol">));</span>
2160
 
<span class="cbracket">}</span>
2161
 
 
2162
 
<span class="type">void</span>
2163
 
<span class="function">set_local_count</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">gint</span><span class="normal"> count</span><span class="symbol">)</span>
2164
 
<span class="cbracket">{</span>
2165
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-private-set">g_private_set</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">count_key</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="glib-Type-Conversion-Macros.html#GINT-TO-POINTER:CAPS">GINT_TO_POINTER</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">count</span><span class="symbol">));</span>
2166
 
<span class="cbracket">}</span></pre></td>
2167
 
      </tr>
2168
 
    </tbody>
2169
 
  </table>
2170
 
</div>
2171
 
 
 
1811
<div class="informalexample"><pre class="programlisting">
 
1812
static GPrivate name_key = G_PRIVATE_INIT (g_free);
 
1813
 
 
1814
// return value should not be freed
 
1815
const gchar *
 
1816
get_local_name (void)
 
1817
{
 
1818
  return g_private_get (&amp;name_key);
 
1819
}
 
1820
 
 
1821
void
 
1822
set_local_name (const gchar *name)
 
1823
{
 
1824
  g_private_replace (&amp;name_key, g_strdup (name));
 
1825
}
 
1826
 
 
1827
 
 
1828
static GPrivate count_key;   // no free function
 
1829
 
 
1830
gint
 
1831
get_local_count (void)
 
1832
{
 
1833
  return GPOINTER_TO_INT (g_private_get (&amp;count_key));
 
1834
}
 
1835
 
 
1836
void
 
1837
set_local_count (gint count)
 
1838
{
 
1839
  g_private_set (&amp;count_key, GINT_TO_POINTER (count));
 
1840
}
 
1841
</pre></div>
2172
1842
<p>
2173
1843
</p>
2174
 
<div class="variablelist"><table border="0" class="variablelist">
2175
 
<colgroup>
 
1844
<div class="variablelist"><table border="0">
2176
1845
<col align="left" valign="top">
2177
 
<col>
2178
 
</colgroup>
2179
1846
<tbody><tr>
2180
1847
<td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
2181
1848
<td>a <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a>
2196
1863
Values are never copied between threads (when a new thread is
2197
1864
created, for example).
2198
1865
</p>
2199
 
<div class="variablelist"><table border="0" class="variablelist">
2200
 
<colgroup>
 
1866
<div class="variablelist"><table border="0">
2201
1867
<col align="left" valign="top">
2202
 
<col>
2203
 
</colgroup>
2204
1868
<tbody>
2205
1869
<tr>
2206
1870
<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
2227
1891
This function differs from <a class="link" href="glib-Threads.html#g-private-replace" title="g_private_replace ()"><code class="function">g_private_replace()</code></a> in the following way:
2228
1892
the <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> for <em class="parameter"><code>key</code></em> is not called on the old value.
2229
1893
</p>
2230
 
<div class="variablelist"><table border="0" class="variablelist">
2231
 
<colgroup>
 
1894
<div class="variablelist"><table border="0">
2232
1895
<col align="left" valign="top">
2233
 
<col>
2234
 
</colgroup>
2235
1896
<tbody>
2236
1897
<tr>
2237
1898
<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
2259
1920
the previous value was non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then the <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> handler for
2260
1921
<em class="parameter"><code>key</code></em> is run on it.
2261
1922
</p>
2262
 
<div class="variablelist"><table border="0" class="variablelist">
2263
 
<colgroup>
 
1923
<div class="variablelist"><table border="0">
2264
1924
<col align="left" valign="top">
2265
 
<col>
2266
 
</colgroup>
2267
1925
<tbody>
2268
1926
<tr>
2269
1927
<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
2291
1949
one-time initialization function must have its own unique <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>
2292
1950
struct.
2293
1951
</p>
2294
 
<div class="variablelist"><table border="0" class="variablelist">
2295
 
<colgroup>
 
1952
<div class="variablelist"><table border="0">
2296
1953
<col align="left" valign="top">
2297
 
<col>
2298
 
</colgroup>
2299
1954
<tbody>
2300
1955
<tr>
2301
1956
<td><p><span class="term">volatile <a class="link" href="glib-Threads.html#GOnceStatus" title="enum GOnceStatus"><span class="type">GOnceStatus</span></a> <em class="structfield"><code><a name="GOnce.status"></a>status</code></em>;</span></p></td>
2325
1980
The possible statuses of a one-time initialization function
2326
1981
controlled by a <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct.
2327
1982
</p>
2328
 
<div class="variablelist"><table border="0" class="variablelist">
2329
 
<colgroup>
 
1983
<div class="variablelist"><table border="0">
2330
1984
<col align="left" valign="top">
2331
 
<col>
2332
 
</colgroup>
2333
1985
<tbody>
2334
1986
<tr>
2335
1987
<td><p><a name="G-ONCE-STATUS-NOTCALLED:CAPS"></a><span class="term"><code class="literal">G_ONCE_STATUS_NOTCALLED</code></span></p></td>
2360
2012
</p>
2361
2013
<p>
2362
2014
</p>
2363
 
<div class="informalexample">
2364
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
2365
 
    <tbody>
2366
 
      <tr>
2367
 
        <td class="listing_lines" align="right"><pre>1</pre></td>
2368
 
        <td class="listing_code"><pre class="programlisting"><span class="usertype">GOnce</span><span class="normal"> my_once </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-ONCE-INIT:CAPS">G_ONCE_INIT</a></span><span class="symbol">;</span></pre></td>
2369
 
      </tr>
2370
 
    </tbody>
2371
 
  </table>
2372
 
</div>
2373
 
 
 
2015
<div class="informalexample"><pre class="programlisting">
 
2016
  GOnce my_once = G_ONCE_INIT;
 
2017
</pre></div>
2374
2018
<p>
2375
2019
</p>
2376
2020
<p class="since">Since 2.4</p>
2397
2041
</p>
2398
2042
<p>
2399
2043
</p>
2400
 
<div class="informalexample">
2401
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
2402
 
    <tbody>
2403
 
      <tr>
2404
 
        <td class="listing_lines" align="right"><pre>1
2405
 
2
2406
 
3
2407
 
4
2408
 
5
2409
 
6
2410
 
7
2411
 
8
2412
 
9</pre></td>
2413
 
        <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span>
2414
 
<span class="function">get_debug_flags</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
2415
 
<span class="cbracket">{</span>
2416
 
<span class="normal">  </span><span class="keyword">static</span><span class="normal"> </span><span class="usertype">GOnce</span><span class="normal"> my_once </span><span class="symbol">=</span><span class="normal"> <a href="glib-Threads.html#G-ONCE-INIT:CAPS">G_ONCE_INIT</a></span><span class="symbol">;</span>
2417
 
 
2418
 
<span class="normal">  </span><span class="function"><a href="glib-Threads.html#g-once">g_once</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">my_once</span><span class="symbol">,</span><span class="normal"> parse_debug_flags</span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
2419
 
 
2420
 
<span class="normal">  </span><span class="keyword">return</span><span class="normal"> my_once</span><span class="symbol">.</span><span class="normal">retval</span><span class="symbol">;</span>
2421
 
<span class="cbracket">}</span></pre></td>
2422
 
      </tr>
2423
 
    </tbody>
2424
 
  </table>
2425
 
</div>
2426
 
 
 
2044
<div class="informalexample"><pre class="programlisting">
 
2045
  gpointer
 
2046
  get_debug_flags (void)
 
2047
  {
 
2048
    static GOnce my_once = G_ONCE_INIT;
 
2049
 
 
2050
    g_once (&amp;my_once, parse_debug_flags, NULL);
 
2051
 
 
2052
    return my_once.retval;
 
2053
  }
 
2054
</pre></div>
2427
2055
<p>
2428
2056
</p>
2429
 
<div class="variablelist"><table border="0" class="variablelist">
2430
 
<colgroup>
 
2057
<div class="variablelist"><table border="0">
2431
2058
<col align="left" valign="top">
2432
 
<col>
2433
 
</colgroup>
2434
2059
<tbody>
2435
2060
<tr>
2436
2061
<td><p><span class="term"><em class="parameter"><code>once</code></em> :</span></p></td>
2468
2093
</p>
2469
2094
<p>
2470
2095
</p>
2471
 
<div class="informalexample">
2472
 
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
2473
 
    <tbody>
2474
 
      <tr>
2475
 
        <td class="listing_lines" align="right"><pre>1
2476
 
2
2477
 
3
2478
 
4
2479
 
5
2480
 
6
2481
 
7
2482
 
8
2483
 
9
2484
 
10</pre></td>
2485
 
        <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="usertype">gsize</span><span class="normal"> initialization_value </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
2486
 
 
2487
 
<span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="glib-Threads.html#g-once-init-enter">g_once_init_enter</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">initialization_value</span><span class="symbol">))</span>
2488
 
<span class="normal">  </span><span class="cbracket">{</span>
2489
 
<span class="normal">    </span><span class="usertype">gsize</span><span class="normal"> setup_value </span><span class="symbol">=</span><span class="normal"> </span><span class="number">42</span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/** initialization code here **/</span>
2490
 
 
2491
 
<span class="normal">    </span><span class="function"><a href="glib-Threads.html#g-once-init-leave">g_once_init_leave</a></span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">initialization_value</span><span class="symbol">,</span><span class="normal"> setup_value</span><span class="symbol">);</span>
2492
 
<span class="normal">  </span><span class="cbracket">}</span>
2493
 
 
2494
 
<span class="comment">/** use initialization_value here **/</span></pre></td>
2495
 
      </tr>
2496
 
    </tbody>
2497
 
  </table>
2498
 
</div>
2499
 
 
 
2096
<div class="informalexample"><pre class="programlisting">
 
2097
  static gsize initialization_value = 0;
 
2098
 
 
2099
  if (g_once_init_enter (&amp;initialization_value))
 
2100
    {
 
2101
      gsize setup_value = 42; /** initialization code here **/
 
2102
 
 
2103
      g_once_init_leave (&amp;initialization_value, setup_value);
 
2104
    }
 
2105
 
 
2106
  /** use initialization_value here **/
 
2107
</pre></div>
2500
2108
<p>
2501
2109
</p>
2502
 
<div class="variablelist"><table border="0" class="variablelist">
2503
 
<colgroup>
 
2110
<div class="variablelist"><table border="0">
2504
2111
<col align="left" valign="top">
2505
 
<col>
2506
 
</colgroup>
2507
2112
<tbody>
2508
2113
<tr>
2509
2114
<td><p><span class="term"><em class="parameter"><code>location</code></em> :</span></p></td>
2531
2136
releases concurrent threads blocking in <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()"><code class="function">g_once_init_enter()</code></a> on this
2532
2137
initialization variable.
2533
2138
</p>
2534
 
<div class="variablelist"><table border="0" class="variablelist">
2535
 
<colgroup>
 
2139
<div class="variablelist"><table border="0">
2536
2140
<col align="left" valign="top">
2537
 
<col>
2538
 
</colgroup>
2539
2141
<tbody>
2540
2142
<tr>
2541
2143
<td><p><span class="term"><em class="parameter"><code>location</code></em> :</span></p></td>
2573
2175
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
2574
2176
reliably.
2575
2177
</p>
2576
 
<div class="variablelist"><table border="0" class="variablelist">
2577
 
<colgroup>
 
2178
<div class="variablelist"><table border="0">
2578
2179
<col align="left" valign="top">
2579
 
<col>
2580
 
</colgroup>
2581
2180
<tbody>
2582
2181
<tr>
2583
2182
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
2613
2212
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
2614
2213
reliably.
2615
2214
</p>
2616
 
<div class="variablelist"><table border="0" class="variablelist">
2617
 
<colgroup>
 
2215
<div class="variablelist"><table border="0">
2618
2216
<col align="left" valign="top">
2619
 
<col>
2620
 
</colgroup>
2621
2217
<tbody>
2622
2218
<tr>
2623
2219
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
2651
2247
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
2652
2248
reliably.
2653
2249
</p>
2654
 
<div class="variablelist"><table border="0" class="variablelist">
2655
 
<colgroup>
 
2250
<div class="variablelist"><table border="0">
2656
2251
<col align="left" valign="top">
2657
 
<col>
2658
 
</colgroup>
2659
2252
<tbody>
2660
2253
<tr>
2661
2254
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
2682
2275
For portability reasons, you may only lock on the bottom 32 bits of
2683
2276
the pointer.
2684
2277
</p>
2685
 
<div class="variablelist"><table border="0" class="variablelist">
2686
 
<colgroup>
 
2278
<div class="variablelist"><table border="0">
2687
2279
<col align="left" valign="top">
2688
 
<col>
2689
 
</colgroup>
2690
2280
<tbody>
2691
2281
<tr>
2692
2282
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
2713
2303
For portability reasons, you may only lock on the bottom 32 bits of
2714
2304
the pointer.
2715
2305
</p>
2716
 
<div class="variablelist"><table border="0" class="variablelist">
2717
 
<colgroup>
 
2306
<div class="variablelist"><table border="0">
2718
2307
<col align="left" valign="top">
2719
 
<col>
2720
 
</colgroup>
2721
2308
<tbody>
2722
2309
<tr>
2723
2310
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
2749
2336
For portability reasons, you may only lock on the bottom 32 bits of
2750
2337
the pointer.
2751
2338
</p>
2752
 
<div class="variablelist"><table border="0" class="variablelist">
2753
 
<colgroup>
 
2339
<div class="variablelist"><table border="0">
2754
2340
<col align="left" valign="top">
2755
 
<col>
2756
 
</colgroup>
2757
2341
<tbody>
2758
2342
<tr>
2759
2343
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
2775
2359
</div>
2776
2360
<div class="footer">
2777
2361
<hr>
2778
 
          Generated by GTK-Doc V1.18.1</div>
 
2362
          Generated by GTK-Doc V1.18</div>
2779
2363
</body>
2780
2364
</html>
 
 
b'\\ No newline at end of file'