diff options
Diffstat (limited to 'gtk+-mingw/share/gtk-doc/html/gio/GCancellable.html')
| -rw-r--r-- | gtk+-mingw/share/gtk-doc/html/gio/GCancellable.html | 644 |
1 files changed, 0 insertions, 644 deletions
diff --git a/gtk+-mingw/share/gtk-doc/html/gio/GCancellable.html b/gtk+-mingw/share/gtk-doc/html/gio/GCancellable.html deleted file mode 100644 index d878930..0000000 --- a/gtk+-mingw/share/gtk-doc/html/gio/GCancellable.html +++ /dev/null @@ -1,644 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -<title>GCancellable</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="index.html" title="GIO Reference Manual"> -<link rel="up" href="async.html" title="Asynchronous I/O"> -<link rel="prev" href="async.html" title="Asynchronous I/O"> -<link rel="next" href="GAsyncResult.html" title="GAsyncResult"> -<meta name="generator" content="GTK-Doc V1.18 (XML mode)"> -<link rel="stylesheet" href="style.css" type="text/css"> -</head> -<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"> -<tr valign="middle"> -<td><a accesskey="p" href="async.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> -<td><a accesskey="u" href="async.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> -<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> -<th width="100%" align="center">GIO Reference Manual</th> -<td><a accesskey="n" href="GAsyncResult.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> -</tr> -<tr><td colspan="5" class="shortcuts"> -<a href="#GCancellable.synopsis" class="shortcut">Top</a> - | - <a href="#GCancellable.description" class="shortcut">Description</a> - | - <a href="#GCancellable.object-hierarchy" class="shortcut">Object Hierarchy</a> - | - <a href="#GCancellable.signals" class="shortcut">Signals</a> -</td></tr> -</table> -<div class="refentry"> -<a name="GCancellable"></a><div class="titlepage"></div> -<div class="refnamediv"><table width="100%"><tr> -<td valign="top"> -<h2><span class="refentrytitle"><a name="GCancellable.top_of_page"></a>GCancellable</span></h2> -<p>GCancellable — Thread-safe Operation Cancellation Stack</p> -</td> -<td valign="top" align="right"></td> -</tr></table></div> -<div class="refsynopsisdiv"> -<a name="GCancellable.synopsis"></a><h2>Synopsis</h2> -<pre class="synopsis"> -#include <gio/gio.h> - - <a class="link" href="GCancellable.html#GCancellable-struct" title="GCancellable">GCancellable</a>; -<a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> * <a class="link" href="GCancellable.html#g-cancellable-new" title="g_cancellable_new ()">g_cancellable_new</a> (<em class="parameter"><code><span class="type">void</span></code></em>); -<a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> <a class="link" href="GCancellable.html#g-cancellable-is-cancelled" title="g_cancellable_is_cancelled ()">g_cancellable_is_cancelled</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>); -<a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> <a class="link" href="GCancellable.html#g-cancellable-set-error-if-cancelled" title="g_cancellable_set_error_if_cancelled ()">g_cancellable_set_error_if_cancelled</a> - (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>); -<span class="returnvalue">int</span> <a class="link" href="GCancellable.html#g-cancellable-get-fd" title="g_cancellable_get_fd ()">g_cancellable_get_fd</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>); -<a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()">g_cancellable_make_pollfd</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> *pollfd</code></em>); -<span class="returnvalue">void</span> <a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()">g_cancellable_release_fd</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>); -<a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * <a class="link" href="GCancellable.html#g-cancellable-source-new" title="g_cancellable_source_new ()">g_cancellable_source_new</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>); -<a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> (<a class="link" href="GCancellable.html#GCancellableSourceFunc" title="GCancellableSourceFunc ()">*GCancellableSourceFunc</a>) (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>); -<a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> * <a class="link" href="GCancellable.html#g-cancellable-get-current" title="g_cancellable_get_current ()">g_cancellable_get_current</a> (<em class="parameter"><code><span class="type">void</span></code></em>); -<span class="returnvalue">void</span> <a class="link" href="GCancellable.html#g-cancellable-pop-current" title="g_cancellable_pop_current ()">g_cancellable_pop_current</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>); -<span class="returnvalue">void</span> <a class="link" href="GCancellable.html#g-cancellable-push-current" title="g_cancellable_push_current ()">g_cancellable_push_current</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>); -<span class="returnvalue">void</span> <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()">g_cancellable_reset</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>); -<a href="./../glib/glib/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a> <a class="link" href="GCancellable.html#g-cancellable-connect" title="g_cancellable_connect ()">g_cancellable_connect</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, - <em class="parameter"><code><a href="./../gobject/gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> callback</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> data_destroy_func</code></em>); -<span class="returnvalue">void</span> <a class="link" href="GCancellable.html#g-cancellable-disconnect" title="g_cancellable_disconnect ()">g_cancellable_disconnect</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gulong"><span class="type">gulong</span></a> handler_id</code></em>); -<span class="returnvalue">void</span> <a class="link" href="GCancellable.html#g-cancellable-cancel" title="g_cancellable_cancel ()">g_cancellable_cancel</a> (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>); -</pre> -</div> -<div class="refsect1"> -<a name="GCancellable.object-hierarchy"></a><h2>Object Hierarchy</h2> -<pre class="synopsis"> - <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a> - +----GCancellable -</pre> -</div> -<div class="refsect1"> -<a name="GCancellable.signals"></a><h2>Signals</h2> -<pre class="synopsis"> - "<a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'>cancelled</a>" : <a href="./../gobject/gobject/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS"><code class="literal">Run Last</code></a> -</pre> -</div> -<div class="refsect1"> -<a name="GCancellable.description"></a><h2>Description</h2> -<p> -GCancellable is a thread-safe operation cancellation stack used -throughout GIO to allow for cancellation of synchronous and -asynchronous operations. -</p> -</div> -<div class="refsect1"> -<a name="GCancellable.details"></a><h2>Details</h2> -<div class="refsect2"> -<a name="GCancellable-struct"></a><h3>GCancellable</h3> -<pre class="programlisting">typedef struct _GCancellable GCancellable;</pre> -<p> -Allows actions to be cancelled. -</p> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-new"></a><h3>g_cancellable_new ()</h3> -<pre class="programlisting"><a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> * g_cancellable_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> -<p> -Creates a new <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object. -</p> -<p> -Applications that want to start one or more operations -that should be cancellable should create a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> -and pass it to the operations. -</p> -<p> -One <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> can be used in multiple consecutive -operations or in multiple concurrent operations. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody><tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.</td> -</tr></tbody> -</table></div> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-is-cancelled"></a><h3>g_cancellable_is_cancelled ()</h3> -<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> g_cancellable_is_cancelled (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre> -<p> -Checks if a cancellable job has been cancelled. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span> -</td> -</tr> -<tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td> -<a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em> is cancelled, -FALSE if called with <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or if item is not cancelled.</td> -</tr> -</tbody> -</table></div> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-set-error-if-cancelled"></a><h3>g_cancellable_set_error_if_cancelled ()</h3> -<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> 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>, - <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> -<p> -If the <em class="parameter"><code>cancellable</code></em> is cancelled, sets the error to notify -that the operation was cancelled. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span> -</td> -</tr> -<tr> -<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td> -<td> -<a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> to append error state to</td> -</tr> -<tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td> -<a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em> was cancelled, <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if it was not</td> -</tr> -</tbody> -</table></div> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-get-fd"></a><h3>g_cancellable_get_fd ()</h3> -<pre class="programlisting"><span class="returnvalue">int</span> g_cancellable_get_fd (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre> -<p> -Gets the file descriptor for a cancellable job. This can be used to -implement cancellable operations on Unix systems. The returned fd will -turn readable when <em class="parameter"><code>cancellable</code></em> is cancelled. -</p> -<p> -You are not supposed to read from the fd yourself, just check for -readable status. Reading to unset the readable status is done -with <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()"><code class="function">g_cancellable_reset()</code></a>. -</p> -<p> -After a successful return from this function, you should use -<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 returned file descriptor. -</p> -<p> -See also <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()"><code class="function">g_cancellable_make_pollfd()</code></a>. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.</td> -</tr> -<tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td>A valid file descriptor. <code class="literal">-1</code> if the file descriptor -is not supported, or on errors.</td> -</tr> -</tbody> -</table></div> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-make-pollfd"></a><h3>g_cancellable_make_pollfd ()</h3> -<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> 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>, - <em class="parameter"><code><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> *pollfd</code></em>);</pre> -<p> -Creates a <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> corresponding to <em class="parameter"><code>cancellable</code></em>; this can be passed -to <a href="./../glib/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 -for unix systems without a native poll and for portability to -windows. -</p> -<p> -When this function returns <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, you should use -<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 -<em class="parameter"><code>pollfd</code></em>. After a <a href="./../glib/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> -<p> -If this function returns <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, either no <em class="parameter"><code>cancellable</code></em> was given or -resource limits prevent this function from allocating the necessary -structures for polling. (On Linux, you will likely have reached -the maximum number of file descriptors.) The suggested way to handle -these cases is to ignore the <em class="parameter"><code>cancellable</code></em>. -</p> -<p> -You are not supposed to read from the fd yourself, just check for -readable status. Reading to unset the readable status is done -with <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()"><code class="function">g_cancellable_reset()</code></a>. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span> -</td> -</tr> -<tr> -<td><p><span class="term"><em class="parameter"><code>pollfd</code></em> :</span></p></td> -<td>a pointer to a <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GPollFD"><span class="type">GPollFD</span></a> -</td> -</tr> -<tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td> -<a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>pollfd</code></em> was successfully initialized, <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on -failure to prepare the cancellable.</td> -</tr> -</tbody> -</table></div> -<p class="since">Since 2.22</p> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-release-fd"></a><h3>g_cancellable_release_fd ()</h3> -<pre class="programlisting"><span class="returnvalue">void</span> g_cancellable_release_fd (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre> -<p> -Releases a resources previously allocated by <a class="link" href="GCancellable.html#g-cancellable-get-fd" title="g_cancellable_get_fd ()"><code class="function">g_cancellable_get_fd()</code></a> -or <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()"><code class="function">g_cancellable_make_pollfd()</code></a>. -</p> -<p> -For compatibility reasons with older releases, calling this function -is not strictly required, the resources will be automatically freed -when the <em class="parameter"><code>cancellable</code></em> is finalized. However, the <em class="parameter"><code>cancellable</code></em> will -block scarce file descriptors until it is finalized if this function -is not called. This can cause the application to run out of file -descriptors when many <a href="GCancellable.html"><span class="type">GCancellables</span></a> are used at the same time. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody><tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> -</td> -</tr></tbody> -</table></div> -<p class="since">Since 2.22</p> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-source-new"></a><h3>g_cancellable_source_new ()</h3> -<pre class="programlisting"><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * 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> -<p> -Creates a source that triggers if <em class="parameter"><code>cancellable</code></em> is cancelled and -calls its callback of type <a class="link" href="GCancellable.html#GCancellableSourceFunc" title="GCancellableSourceFunc ()"><span class="type">GCancellableSourceFunc</span></a>. This is -primarily useful for attaching to another (non-cancellable) source -with <a href="./../glib/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> -<p> -For convenience, you can call this with a <a href="./../glib/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>, -in which case the source will never trigger. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span> -</td> -</tr> -<tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td>the new <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span> -</td> -</tr> -</tbody> -</table></div> -<p class="since">Since 2.28</p> -</div> -<hr> -<div class="refsect2"> -<a name="GCancellableSourceFunc"></a><h3>GCancellableSourceFunc ()</h3> -<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> (*GCancellableSourceFunc) (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> -<p> -This is the function type of the callback used for the <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a> -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> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>the <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> -</td> -</tr> -<tr> -<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td> -<td>data passed in by the user.</td> -</tr> -<tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td>it should return <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if the source should be removed.</td> -</tr> -</tbody> -</table></div> -<p class="since">Since 2.28</p> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-get-current"></a><h3>g_cancellable_get_current ()</h3> -<pre class="programlisting"><a class="link" href="GCancellable.html" title="GCancellable"><span class="returnvalue">GCancellable</span></a> * g_cancellable_get_current (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> -<p> -Gets the top cancellable from the stack. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody><tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> from the top of the stack, or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> -if the stack is empty. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span> -</td> -</tr></tbody> -</table></div> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-pop-current"></a><h3>g_cancellable_pop_current ()</h3> -<pre class="programlisting"><span class="returnvalue">void</span> g_cancellable_pop_current (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre> -<p> -Pops <em class="parameter"><code>cancellable</code></em> off the cancellable stack (verifying that <em class="parameter"><code>cancellable</code></em> -is on the top of the stack). -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody><tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object</td> -</tr></tbody> -</table></div> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-push-current"></a><h3>g_cancellable_push_current ()</h3> -<pre class="programlisting"><span class="returnvalue">void</span> g_cancellable_push_current (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre> -<p> -Pushes <em class="parameter"><code>cancellable</code></em> onto the cancellable stack. The current -cancellable can then be received using <a class="link" href="GCancellable.html#g-cancellable-get-current" title="g_cancellable_get_current ()"><code class="function">g_cancellable_get_current()</code></a>. -</p> -<p> -This is useful when implementing cancellable operations in -code that does not allow you to pass down the cancellable object. -</p> -<p> -This is typically called automatically by e.g. <a class="link" href="GFile.html" title="GFile"><span class="type">GFile</span></a> operations, -so you rarely have to call this yourself. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody><tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object</td> -</tr></tbody> -</table></div> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-reset"></a><h3>g_cancellable_reset ()</h3> -<pre class="programlisting"><span class="returnvalue">void</span> g_cancellable_reset (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre> -<p> -Resets <em class="parameter"><code>cancellable</code></em> to its uncancelled state. -</p> -<p> -If cancellable is currently in use by any cancellable operation -then the behavior of this function is undefined. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody><tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.</td> -</tr></tbody> -</table></div> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-connect"></a><h3>g_cancellable_connect ()</h3> -<pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gulong"><span class="returnvalue">gulong</span></a> g_cancellable_connect (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, - <em class="parameter"><code><a href="./../gobject/gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> callback</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> data_destroy_func</code></em>);</pre> -<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> -signal. Also handles the race condition that may happen -if the cancellable is cancelled right before connecting. -</p> -<p> -<em class="parameter"><code>callback</code></em> is called at most once, either directly at the -time of the connect if <em class="parameter"><code>cancellable</code></em> is already cancelled, -or when <em class="parameter"><code>cancellable</code></em> is cancelled in some thread. -</p> -<p> -<em class="parameter"><code>data_destroy_func</code></em> will be called when the handler is -disconnected, or immediately if the cancellable is already -cancelled. -</p> -<p> -See <a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> for details on how to use this. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>A <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.</td> -</tr> -<tr> -<td><p><span class="term"><em class="parameter"><code>callback</code></em> :</span></p></td> -<td>The <a href="./../gobject/gobject/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> to connect.</td> -</tr> -<tr> -<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td> -<td>Data to pass to <em class="parameter"><code>callback</code></em>.</td> -</tr> -<tr> -<td><p><span class="term"><em class="parameter"><code>data_destroy_func</code></em> :</span></p></td> -<td>Free function for <em class="parameter"><code>data</code></em> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span> -</td> -</tr> -<tr> -<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> -<td>The id of the signal handler or 0 if <em class="parameter"><code>cancellable</code></em> has already -been cancelled.</td> -</tr> -</tbody> -</table></div> -<p class="since">Since 2.22</p> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-disconnect"></a><h3>g_cancellable_disconnect ()</h3> -<pre class="programlisting"><span class="returnvalue">void</span> g_cancellable_disconnect (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>, - <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gulong"><span class="type">gulong</span></a> handler_id</code></em>);</pre> -<p> -Disconnects a handler from a cancellable instance similar to -<a href="./../gobject/gobject/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a>. Additionally, in the event that a -signal handler is currently running, this call will block until the -handler has finished. Calling this function from a -<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 -deadlock. -</p> -<p> -This avoids a race condition where a thread cancels at the -same time as the cancellable operation is finished and the -signal handler is removed. See <a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> for -details on how to use this. -</p> -<p> -If <em class="parameter"><code>cancellable</code></em> is <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or <em class="parameter"><code>handler_id</code></em> is <code class="literal">0</code> this function does -nothing. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>A <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span> -</td> -</tr> -<tr> -<td><p><span class="term"><em class="parameter"><code>handler_id</code></em> :</span></p></td> -<td>Handler id of the handler to be disconnected, or <code class="literal">0</code>.</td> -</tr> -</tbody> -</table></div> -<p class="since">Since 2.22</p> -</div> -<hr> -<div class="refsect2"> -<a name="g-cancellable-cancel"></a><h3>g_cancellable_cancel ()</h3> -<pre class="programlisting"><span class="returnvalue">void</span> g_cancellable_cancel (<em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre> -<p> -Will set <em class="parameter"><code>cancellable</code></em> to cancelled, and will emit the -<a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> signal. (However, see the warning about -race conditions in the documentation for that signal if you are -planning to connect to it.) -</p> -<p> -This function is thread-safe. In other words, you can safely call -it from a thread other than the one running the operation that was -passed the <em class="parameter"><code>cancellable</code></em>. -</p> -<p> -The convention within gio is that cancelling an asynchronous -operation causes it to complete asynchronously. That is, if you -cancel the operation from the same thread in which it is running, -then the operation's <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> will not be invoked until -the application returns to the main loop. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody><tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.</td> -</tr></tbody> -</table></div> -</div> -</div> -<div class="refsect1"> -<a name="GCancellable.signal-details"></a><h2>Signal Details</h2> -<div class="refsect2"> -<a name="GCancellable-cancelled"></a><h3>The <code class="literal">"cancelled"</code> signal</h3> -<pre class="programlisting"><span class="returnvalue">void</span> user_function (<a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable, - <a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data) : <a href="./../gobject/gobject/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS"><code class="literal">Run Last</code></a></pre> -<p> -Emitted when the operation has been cancelled. -</p> -<p> -Can be used by implementations of cancellable operations. If the -operation is cancelled from another thread, the signal will be -emitted in the thread that cancelled the operation, not the -thread that is running the operation. -</p> -<p> -Note that disconnecting from this signal (or any signal) in a -multi-threaded program is prone to race conditions. For instance -it is possible that a signal handler may be invoked even -<span class="emphasis"><em>after</em></span> a call to -<a href="./../gobject/gobject/gobject-Signals.html#g-signal-handler-disconnect"><code class="function">g_signal_handler_disconnect()</code></a> for that handler has already -returned. -</p> -<p> -There is also a problem when cancellation happen -right before connecting to the signal. If this happens the -signal will unexpectedly not be emitted, and checking before -connecting to the signal leaves a race condition where this is -still happening. -</p> -<p> -In order to make it safe and easy to connect handlers there -are two helper functions: <a class="link" href="GCancellable.html#g-cancellable-connect" title="g_cancellable_connect ()"><code class="function">g_cancellable_connect()</code></a> and -<a class="link" href="GCancellable.html#g-cancellable-disconnect" title="g_cancellable_disconnect ()"><code class="function">g_cancellable_disconnect()</code></a> which protect against problems -like this. -</p> -<p> -An example of how to us this: -</p> -<div class="informalexample"><pre class="programlisting"> - /* Make sure we don't do any unnecessary work if already cancelled */ - if (g_cancellable_set_error_if_cancelled (cancellable)) - return; - /* Set up all the data needed to be able to - * handle cancellation of the operation */ - my_data = my_data_new (...); - - id = 0; - if (cancellable) - id = g_cancellable_connect (cancellable, - G_CALLBACK (cancelled_handler) - data, NULL); - - /* cancellable operation here... */ - - g_cancellable_disconnect (cancellable, id); - - /* cancelled_handler is never called after this, it - * is now safe to free the data */ - my_data_free (my_data); -</pre></div> -<p> -</p> -<p> -Note that the cancelled signal is emitted in the thread that -the user cancelled from, which may be the main thread. So, the -cancellable signal should not do something that can block. -</p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td> -<td>a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.</td> -</tr> -<tr> -<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td> -<td>user data set when the signal handler was connected.</td> -</tr> -</tbody> -</table></div> -</div> -</div> -</div> -<div class="footer"> -<hr> - Generated by GTK-Doc V1.18</div> -</body> -</html>
\ No newline at end of file |