docs/reference/gio/html/gio-GIOScheduler.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>GIOScheduler</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GIO Reference Manual">
   8 <link rel="up" href="async.html" title="Asynchronous I/O">
   9 <link rel="prev" href="GAsyncResult.html" title="GAsyncResult">
  10 <link rel="next" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="GAsyncResult.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="async.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GIO Reference Manual</th>
  21 <td><a accesskey="n" href="GSimpleAsyncResult.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#gio-GIOScheduler.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#gio-GIOScheduler.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="gio-GIOScheduler"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="gio-GIOScheduler.top_of_page"></a>GIOScheduler</span></h2>
  34 <p>GIOScheduler — I/O Scheduler</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="gio-GIOScheduler.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;gio/gio.h&gt;
  42
  43                     <a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob">GIOSchedulerJob</a>;
  44 <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            (<a class="link" href="gio-GIOScheduler.html#GIOSchedulerJobFunc" title="GIOSchedulerJobFunc ()">*GIOSchedulerJobFunc</a>)              (<em class="parameter"><code><a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a> *job</code></em>,
  45                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
  46                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  47 <span class="returnvalue">void</span>                <a class="link" href="gio-GIOScheduler.html#g-io-scheduler-push-job" title="g_io_scheduler_push_job ()">g_io_scheduler_push_job</a>             (<em class="parameter"><code><a class="link" href="gio-GIOScheduler.html#GIOSchedulerJobFunc" title="GIOSchedulerJobFunc ()"><span class="type">GIOSchedulerJobFunc</span></a> job_func</code></em>,
  48                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
  49                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>,
  50                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> io_priority</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);
  52 <span class="returnvalue">void</span>                <a class="link" href="gio-GIOScheduler.html#g-io-scheduler-cancel-all-jobs" title="g_io_scheduler_cancel_all_jobs ()">g_io_scheduler_cancel_all_jobs</a>      (<em class="parameter"><code><span class="type">void</span></code></em>);
  53 <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="gio-GIOScheduler.html#g-io-scheduler-job-send-to-mainloop" title="g_io_scheduler_job_send_to_mainloop ()">g_io_scheduler_job_send_to_mainloop</a> (<em class="parameter"><code><a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a> *job</code></em>,
  54                                                          <em class="parameter"><code><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
  55                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
  56                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);
  57 <span class="returnvalue">void</span>                <a class="link" href="gio-GIOScheduler.html#g-io-scheduler-job-send-to-mainloop-async" title="g_io_scheduler_job_send_to_mainloop_async ()">g_io_scheduler_job_send_to_mainloop_async</a>
  58                                                         (<em class="parameter"><code><a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a> *job</code></em>,
  59                                                          <em class="parameter"><code><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
  60                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
  61                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);
  62 </pre>
  63 </div>
  64 <div class="refsect1">
  65 <a name="gio-GIOScheduler.description"></a><h2>Description</h2>
  66 <p>
  67 Schedules asynchronous I/O operations. <span class="type">GIOScheduler</span> integrates
  68 into the main event loop (<a href="./../glib/glib/glib-The-Main-Event-Loop.html#GMainLoop"><span class="type">GMainLoop</span></a>) and uses threads.
  69 </p>
  70 <p>
  71 </p>
  72 <p><a name="io-priority"></a>
  73 Each I/O operation has a priority, and the scheduler uses the priorities
  74 to determine the order in which operations are executed. They are
  75 <span class="emphasis"><em>not</em></span> used to determine system-wide I/O scheduling.
  76 Priorities are integers, with lower numbers indicating higher priority.
  77 It is recommended to choose priorities between <a href="./../glib/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-LOW:CAPS"><code class="literal">G_PRIORITY_LOW</code></a> and
  78 <a href="./../glib/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-HIGH:CAPS"><code class="literal">G_PRIORITY_HIGH</code></a>, with <a href="./../glib/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT:CAPS"><code class="literal">G_PRIORITY_DEFAULT</code></a> as a default.
  79 </p>
  80 <p>
  81 </p>
  82 </div>
  83 <div class="refsect1">
  84 <a name="gio-GIOScheduler.details"></a><h2>Details</h2>
  85 <div class="refsect2">
  86 <a name="GIOSchedulerJob"></a><h3>GIOSchedulerJob</h3>
  87 <pre class="programlisting">typedef struct _GIOSchedulerJob GIOSchedulerJob;</pre>
  88 <p>
  89 Opaque class for defining and scheduling IO jobs.
  90 </p>
  91 </div>
  92 <hr>
  93 <div class="refsect2">
  94 <a name="GIOSchedulerJobFunc"></a><h3>GIOSchedulerJobFunc ()</h3>
  95 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            (*GIOSchedulerJobFunc)              (<em class="parameter"><code><a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a> *job</code></em>,
  96                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
  97                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
  98 <p>
  99 I/O Job function.
 100 </p>
 101 <p>
 102 Long-running jobs should periodically check the <em class="parameter"><code>cancellable</code></em>
 103 to see if they have been cancelled.
 104 </p>
 105 <div class="variablelist"><table border="0">
 106 <col align="left" valign="top">
 107 <tbody>
 108 <tr>
 109 <td><p><span class="term"><em class="parameter"><code>job</code></em> :</span></p></td>
 110 <td>a <a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a>.</td>
 111 </tr>
 112 <tr>
 113 <td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
 114 <td>optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>
 115 </tr>
 116 <tr>
 117 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 118 <td>the data to pass to callback function</td>
 119 </tr>
 120 <tr>
 121 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 122 <td>
 123 <a href="./../glib/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if this function should be called again to
 124 complete the job, <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if the job is complete (or cancelled)</td>
 125 </tr>
 126 </tbody>
 127 </table></div>
 128 </div>
 129 <hr>
 130 <div class="refsect2">
 131 <a name="g-io-scheduler-push-job"></a><h3>g_io_scheduler_push_job ()</h3>
 132 <pre class="programlisting"><span class="returnvalue">void</span>                g_io_scheduler_push_job             (<em class="parameter"><code><a class="link" href="gio-GIOScheduler.html#GIOSchedulerJobFunc" title="GIOSchedulerJobFunc ()"><span class="type">GIOSchedulerJobFunc</span></a> job_func</code></em>,
 133                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
 134                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>,
 135                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a> io_priority</code></em>,
 136                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>);</pre>
 137 <p>
 138 Schedules the I/O job to run in another thread.
 139 </p>
 140 <p>
 141 <em class="parameter"><code>notify</code></em> will be called on <em class="parameter"><code>user_data</code></em> after <em class="parameter"><code>job_func</code></em> has returned,
 142 regardless whether the job was cancelled or has run to completion.
 143 </p>
 144 <p>
 145 If <em class="parameter"><code>cancellable</code></em> is not <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, it can be used to cancel the I/O job
 146 by calling <a class="link" href="GCancellable.html#g-cancellable-cancel" title="g_cancellable_cancel ()"><code class="function">g_cancellable_cancel()</code></a> or by calling
 147 <a class="link" href="gio-GIOScheduler.html#g-io-scheduler-cancel-all-jobs" title="g_io_scheduler_cancel_all_jobs ()"><code class="function">g_io_scheduler_cancel_all_jobs()</code></a>.
 148 </p>
 149 <div class="variablelist"><table border="0">
 150 <col align="left" valign="top">
 151 <tbody>
 152 <tr>
 153 <td><p><span class="term"><em class="parameter"><code>job_func</code></em> :</span></p></td>
 154 <td>a <a class="link" href="gio-GIOScheduler.html#GIOSchedulerJobFunc" title="GIOSchedulerJobFunc ()"><span class="type">GIOSchedulerJobFunc</span></a>.</td>
 155 </tr>
 156 <tr>
 157 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 158 <td>data to pass to <em class="parameter"><code>job_func</code></em>
 159 </td>
 160 </tr>
 161 <tr>
 162 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
 163 <td>a <a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> for <em class="parameter"><code>user_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>
 164 </td>
 165 </tr>
 166 <tr>
 167 <td><p><span class="term"><em class="parameter"><code>io_priority</code></em> :</span></p></td>
 168 <td>the I/O priority
 169 of the request.</td>
 170 </tr>
 171 <tr>
 172 <td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
 173 <td>optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object, <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>
 174 </tr>
 175 </tbody>
 176 </table></div>
 177 </div>
 178 <hr>
 179 <div class="refsect2">
 180 <a name="g-io-scheduler-cancel-all-jobs"></a><h3>g_io_scheduler_cancel_all_jobs ()</h3>
 181 <pre class="programlisting"><span class="returnvalue">void</span>                g_io_scheduler_cancel_all_jobs      (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 182 <p>
 183 Cancels all cancellable I/O jobs.
 184 </p>
 185 <p>
 186 A job is cancellable if a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> was passed into
 187 <a class="link" href="gio-GIOScheduler.html#g-io-scheduler-push-job" title="g_io_scheduler_push_job ()"><code class="function">g_io_scheduler_push_job()</code></a>.
 188 </p>
 189 </div>
 190 <hr>
 191 <div class="refsect2">
 192 <a name="g-io-scheduler-job-send-to-mainloop"></a><h3>g_io_scheduler_job_send_to_mainloop ()</h3>
 193 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            g_io_scheduler_job_send_to_mainloop (<em class="parameter"><code><a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a> *job</code></em>,
 194                                                          <em class="parameter"><code><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
 195                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
 196                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
 197 <p>
 198 Used from an I/O job to send a callback to be run in the thread
 199 that the job was started from, waiting for the result (and thus
 200 blocking the I/O job).
 201 </p>
 202 <div class="variablelist"><table border="0">
 203 <col align="left" valign="top">
 204 <tbody>
 205 <tr>
 206 <td><p><span class="term"><em class="parameter"><code>job</code></em> :</span></p></td>
 207 <td>a <a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a>
 208 </td>
 209 </tr>
 210 <tr>
 211 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 212 <td>a <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> callback that will be called in the original thread</td>
 213 </tr>
 214 <tr>
 215 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 216 <td>data to pass to <em class="parameter"><code>func</code></em>
 217 </td>
 218 </tr>
 219 <tr>
 220 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
 221 <td>a <a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> for <em class="parameter"><code>user_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>
 222 </td>
 223 </tr>
 224 <tr>
 225 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 226 <td>The return value of <em class="parameter"><code>func</code></em>
 227 </td>
 228 </tr>
 229 </tbody>
 230 </table></div>
 231 </div>
 232 <hr>
 233 <div class="refsect2">
 234 <a name="g-io-scheduler-job-send-to-mainloop-async"></a><h3>g_io_scheduler_job_send_to_mainloop_async ()</h3>
 235 <pre class="programlisting"><span class="returnvalue">void</span>                g_io_scheduler_job_send_to_mainloop_async
 236                                                         (<em class="parameter"><code><a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a> *job</code></em>,
 237                                                          <em class="parameter"><code><a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> func</code></em>,
 238                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>,
 239                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> notify</code></em>);</pre>
 240 <p>
 241 Used from an I/O job to send a callback to be run asynchronously in
 242 the thread that the job was started from. The callback will be run
 243 when the main loop is available, but at that time the I/O job might
 244 have finished. The return value from the callback is ignored.
 245 </p>
 246 <p>
 247 Note that if you are passing the <em class="parameter"><code>user_data</code></em> from <a class="link" href="gio-GIOScheduler.html#g-io-scheduler-push-job" title="g_io_scheduler_push_job ()"><code class="function">g_io_scheduler_push_job()</code></a>
 248 on to this function you have to ensure that it is not freed before
 249 <em class="parameter"><code>func</code></em> is called, either by passing <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> as <em class="parameter"><code>notify</code></em> to
 250 <a class="link" href="gio-GIOScheduler.html#g-io-scheduler-push-job" title="g_io_scheduler_push_job ()"><code class="function">g_io_scheduler_push_job()</code></a> or by using refcounting for <em class="parameter"><code>user_data</code></em>.
 251 </p>
 252 <div class="variablelist"><table border="0">
 253 <col align="left" valign="top">
 254 <tbody>
 255 <tr>
 256 <td><p><span class="term"><em class="parameter"><code>job</code></em> :</span></p></td>
 257 <td>a <a class="link" href="gio-GIOScheduler.html#GIOSchedulerJob" title="GIOSchedulerJob"><span class="type">GIOSchedulerJob</span></a>
 258 </td>
 259 </tr>
 260 <tr>
 261 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 262 <td>a <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> callback that will be called in the original thread</td>
 263 </tr>
 264 <tr>
 265 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 266 <td>data to pass to <em class="parameter"><code>func</code></em>
 267 </td>
 268 </tr>
 269 <tr>
 270 <td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
 271 <td>a <a href="./../glib/glib/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> for <em class="parameter"><code>user_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>
 272 </td>
 273 </tr>
 274 </tbody>
 275 </table></div>
 276 </div>
 277 </div>
 278 </div>
 279 <div class="footer">
 280 <hr>
 281           Generated by GTK-Doc V1.18</div>
 282 </body>
 283 </html>