245
245
<td class="parameter_name"><p>cancellable</p></td>
246
<td class="parameter_description"><p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
246
<td class="parameter_description"><p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
247
247
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
251
251
<div class="refsect3">
252
252
<a name="id-1.4.5.2.9.3.6"></a><h4>Returns</h4>
253
<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em>
253
<p> <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em>
255
FALSE if called with <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or if item is not cancelled.</p>
255
FALSE if called with <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or if item is not cancelled.</p>
260
260
<div class="refsect2">
261
261
<a name="g-cancellable-set-error-if-cancelled"></a><h3>g_cancellable_set_error_if_cancelled ()</h3>
262
<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>
262
<pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>
263
263
g_cancellable_set_error_if_cancelled (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
264
<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
264
<em class="parameter"><code><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
265
265
<p>If the <em class="parameter"><code>cancellable</code></em>
266
266
is cancelled, sets the error to notify
267
267
that the operation was cancelled.</p>
278
278
<td class="parameter_name"><p>cancellable</p></td>
279
<td class="parameter_description"><p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
279
<td class="parameter_description"><p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
280
280
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
283
283
<td class="parameter_name"><p>error</p></td>
284
<td class="parameter_description"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> to append error state to</p></td>
284
<td class="parameter_description"><p><a href="../glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> to append error state to</p></td>
285
285
<td class="parameter_annotations"> </td>
290
290
<div class="refsect3">
291
291
<a name="id-1.4.5.2.9.4.6"></a><h4>Returns</h4>
292
<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em>
293
was cancelled, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if it was not</p>
292
<p> <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em>
293
was cancelled, <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if it was not</p>
336
336
<div class="refsect2">
337
337
<a name="g-cancellable-make-pollfd"></a><h3>g_cancellable_make_pollfd ()</h3>
338
<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>
338
<pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>
339
339
g_cancellable_make_pollfd (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
340
<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> *pollfd</code></em>);</pre>
341
<p>Creates a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> corresponding to <em class="parameter"><code>cancellable</code></em>
340
<em class="parameter"><code><a href="../glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> *pollfd</code></em>);</pre>
341
<p>Creates a <a href="../glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> corresponding to <em class="parameter"><code>cancellable</code></em>
342
342
; this can be passed
343
to <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-poll"><code class="function">g_poll()</code></a> and used to poll for cancellation. This is useful both
343
to <a href="../glib/glib-The-Main-Event-Loop.html#g-poll"><code class="function">g_poll()</code></a> and used to poll for cancellation. This is useful both
344
344
for unix systems without a native poll and for portability to
346
<p>When this function returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, you should use
346
<p>When this function returns <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, you should use
347
347
<a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a> to free up resources allocated for the
348
348
<em class="parameter"><code>pollfd</code></em>
349
. After a <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> return, do not call <a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a>.</p>
350
<p>If this function returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, either no <em class="parameter"><code>cancellable</code></em>
349
. After a <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> return, do not call <a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a>.</p>
350
<p>If this function returns <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, either no <em class="parameter"><code>cancellable</code></em>
352
352
resource limits prevent this function from allocating the necessary
353
353
structures for polling. (On Linux, you will likely have reached
370
370
<td class="parameter_name"><p>cancellable</p></td>
371
<td class="parameter_description"><p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
371
<td class="parameter_description"><p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
372
372
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
375
375
<td class="parameter_name"><p>pollfd</p></td>
376
<td class="parameter_description"><p>a pointer to a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a></p></td>
376
<td class="parameter_description"><p>a pointer to a <a href="../glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a></p></td>
377
377
<td class="parameter_annotations"> </td>
382
382
<div class="refsect3">
383
383
<a name="id-1.4.5.2.9.6.9"></a><h4>Returns</h4>
384
<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>pollfd</code></em>
385
was successfully initialized, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on
384
<p> <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>pollfd</code></em>
385
was successfully initialized, <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on
386
386
failure to prepare the cancellable.</p>
424
424
<div class="refsect2">
425
425
<a name="g-cancellable-source-new"></a><h3>g_cancellable_source_new ()</h3>
426
<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> *
426
<pre class="programlisting"><a href="../glib/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> *
427
427
g_cancellable_source_new (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
428
428
<p>Creates a source that triggers if <em class="parameter"><code>cancellable</code></em>
430
430
calls its callback of type <a class="link" href="GCancellable.html#GCancellableSourceFunc" title="GCancellableSourceFunc ()"><span class="type">GCancellableSourceFunc</span></a>. This is
431
431
primarily useful for attaching to another (non-cancellable) source
432
with <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-source-add-child-source"><code class="function">g_source_add_child_source()</code></a> to add cancellability to it.</p>
433
<p>For convenience, you can call this with a <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>,
432
with <a href="../glib/glib-The-Main-Event-Loop.html#g-source-add-child-source"><code class="function">g_source_add_child_source()</code></a> to add cancellability to it.</p>
433
<p>For convenience, you can call this with a <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>,
434
434
in which case the source will never trigger.</p>
435
435
<div class="refsect3">
436
436
<a name="id-1.4.5.2.9.8.6"></a><h4>Parameters</h4>
444
444
<td class="parameter_name"><p>cancellable</p></td>
445
<td class="parameter_description"><p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
445
<td class="parameter_description"><p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
446
446
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
450
450
<div class="refsect3">
451
451
<a name="id-1.4.5.2.9.8.7"></a><h4>Returns</h4>
452
<p> the new <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>. </p>
452
<p> the new <a href="../glib/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>. </p>
453
453
<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p>
455
455
<p class="since">Since 2.28</p>
458
458
<div class="refsect2">
459
459
<a name="GCancellableSourceFunc"></a><h3>GCancellableSourceFunc ()</h3>
460
<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>
460
<pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>
461
461
<span class="c_punctuation">(</span>*GCancellableSourceFunc<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
462
<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
463
<p>This is the function type of the callback used for the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>
462
<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
463
<p>This is the function type of the callback used for the <a href="../glib/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>
464
464
returned by <a class="link" href="GCancellable.html#g-cancellable-source-new" title="g_cancellable_source_new ()"><code class="function">g_cancellable_source_new()</code></a>.</p>
465
465
<div class="refsect3">
466
466
<a name="id-1.4.5.2.9.9.5"></a><h4>Parameters</h4>
500
500
<div class="refsect3">
501
501
<a name="id-1.4.5.2.9.10.5"></a><h4>Returns</h4>
502
502
<p> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> from the top
503
of the stack, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the stack is empty. </p>
503
of the stack, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the stack is empty. </p>
504
504
<p><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p>
586
586
<div class="refsect2">
587
587
<a name="g-cancellable-connect"></a><h3>g_cancellable_connect ()</h3>
588
<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a>
588
<pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a>
589
589
g_cancellable_connect (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
590
<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> callback</code></em>,
591
<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
592
<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> data_destroy_func</code></em>);</pre>
590
<em class="parameter"><code><a href="../gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> callback</code></em>,
591
<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>,
592
<em class="parameter"><code><a href="../glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> data_destroy_func</code></em>);</pre>
593
593
<p>Convenience function to connect to the <a class="link" href="GCancellable.html#GCancellable-cancelled" title="The “cancelled” signal"><span class="type">“cancelled”</span></a>
594
594
signal. Also handles the race condition that may happen
595
595
if the cancellable is cancelled right before connecting.</p>
639
639
<td class="parameter_name"><p>data_destroy_func</p></td>
640
640
<td class="parameter_description"><p> Free function for <em class="parameter"><code>data</code></em>
641
or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
641
or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
642
642
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
658
658
<a name="g-cancellable-disconnect"></a><h3>g_cancellable_disconnect ()</h3>
659
659
<pre class="programlisting"><span class="returnvalue">void</span>
660
660
g_cancellable_disconnect (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
661
<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gulong"><span class="type">gulong</span></a> handler_id</code></em>);</pre>
661
<em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gulong"><span class="type">gulong</span></a> handler_id</code></em>);</pre>
662
662
<p>Disconnects a handler from a cancellable instance similar to
663
<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a>. Additionally, in the event that a
663
<a href="../gobject/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a>. Additionally, in the event that a
664
664
signal handler is currently running, this call will block until the
665
665
handler has finished. Calling this function from a
666
666
<a class="link" href="GCancellable.html#GCancellable-cancelled" title="The “cancelled” signal"><span class="type">“cancelled”</span></a> signal handler will therefore result in a
670
670
signal handler is removed. See <a class="link" href="GCancellable.html#GCancellable-cancelled" title="The “cancelled” signal"><span class="type">“cancelled”</span></a> for
671
671
details on how to use this.</p>
672
672
<p>If <em class="parameter"><code>cancellable</code></em>
673
is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or <em class="parameter"><code>handler_id</code></em>
673
is <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or <em class="parameter"><code>handler_id</code></em>
674
674
is <code class="literal">0</code> this function does
676
676
<div class="refsect3">
686
686
<td class="parameter_name"><p>cancellable</p></td>
687
<td class="parameter_description"><p> A <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
687
<td class="parameter_description"><p> A <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td>
688
688
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td>
747
747
<a name="GCancellable-cancelled"></a><h3>The <code class="literal">“cancelled”</code> signal</h3>
748
748
<pre class="programlisting"><span class="returnvalue">void</span>
749
749
user_function (<a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable,
750
<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre>
750
<a href="../glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre>
751
751
<p>Emitted when the operation has been cancelled.</p>
752
752
<p>Can be used by implementations of cancellable operations. If the
753
753
operation is cancelled from another thread, the signal will be
756
756
<p>Note that disconnecting from this signal (or any signal) in a
757
757
multi-threaded program is prone to race conditions. For instance
758
758
it is possible that a signal handler may be invoked even after
759
a call to <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a> for that handler has
759
a call to <a href="../gobject/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a> for that handler has
760
760
already returned.</p>
761
761
<p>There is also a problem when cancellation happens right before
762
762
connecting to the signal. If this happens the signal will
795
<td class="listing_code"><pre class="programlisting"><span class="comment">// Make sure we don't do unnecessary work if already cancelled</span>
796
<span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GCancellable.html#g-cancellable-set-error-if-cancelled">g_cancellable_set_error_if_cancelled</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancellable</span><span class="symbol">,</span><span class="normal"> error</span><span class="symbol">))</span>
797
<span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span>
799
<span class="comment">// Set up all the data needed to be able to handle cancellation</span>
800
<span class="comment">// of the operation</span>
801
<span class="normal">my_data </span><span class="symbol">=</span><span class="normal"> </span><span class="function">my_data_new</span><span class="normal"> </span><span class="symbol">(...);</span>
803
<span class="normal">id </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
804
<span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancellable</span><span class="symbol">)</span>
805
<span class="normal"> id </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GCancellable.html#g-cancellable-connect">g_cancellable_connect</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancellable</span><span class="symbol">,</span>
806
<span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancelled_handler</span><span class="symbol">)</span>
807
<span class="normal"> data</span><span class="symbol">,</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
809
<span class="comment">// cancellable operation here...</span>
811
<span class="function"><a href="GCancellable.html#g-cancellable-disconnect">g_cancellable_disconnect</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">cancellable</span><span class="symbol">,</span><span class="normal"> id</span><span class="symbol">);</span>
813
<span class="comment">// cancelled_handler is never called after this, it is now safe</span>
814
<span class="comment">// to free the data</span>
815
<span class="function">my_data_free</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">my_data</span><span class="symbol">);</span></pre></td>
795
<td class="listing_code"><pre class="programlisting"><span class="gtkdoc slc">// Make sure we don't do unnecessary work if already cancelled</span>
796
<span class="keyword">if</span> <span class="gtkdoc opt">(</span><span class="function"><a href="GCancellable.html#g-cancellable-set-error-if-cancelled">g_cancellable_set_error_if_cancelled</a></span> <span class="gtkdoc opt">(</span>cancellable<span class="gtkdoc opt">,</span> error<span class="gtkdoc opt">))</span>
797
<span class="keyword">return</span><span class="gtkdoc opt">;</span>
799
<span class="gtkdoc slc">// Set up all the data needed to be able to handle cancellation</span>
800
<span class="gtkdoc slc">// of the operation</span>
801
my_data <span class="gtkdoc opt">=</span> <span class="function">my_data_new</span> <span class="gtkdoc opt">(...);</span>
803
id <span class="gtkdoc opt">=</span> <span class="number">0</span><span class="gtkdoc opt">;</span>
804
<span class="keyword">if</span> <span class="gtkdoc opt">(</span>cancellable<span class="gtkdoc opt">)</span>
805
id <span class="gtkdoc opt">=</span> <span class="function"><a href="GCancellable.html#g-cancellable-connect">g_cancellable_connect</a></span> <span class="gtkdoc opt">(</span>cancellable<span class="gtkdoc opt">,</span>
806
<span class="function"><a href="../gobject/gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a></span> <span class="gtkdoc opt">(</span>cancelled_handler<span class="gtkdoc opt">)</span>
807
data<span class="gtkdoc opt">,</span> NULL<span class="gtkdoc opt">);</span>
809
<span class="gtkdoc slc">// cancellable operation here...</span>
811
<span class="function"><a href="GCancellable.html#g-cancellable-disconnect">g_cancellable_disconnect</a></span> <span class="gtkdoc opt">(</span>cancellable<span class="gtkdoc opt">,</span> id<span class="gtkdoc opt">);</span>
813
<span class="gtkdoc slc">// cancelled_handler is never called after this, it is now safe</span>
814
<span class="gtkdoc slc">// to free the data</span>
815
<span class="function">my_data_free</span> <span class="gtkdoc opt">(</span>my_data<span class="gtkdoc opt">);</span></pre></td>