~ubuntu-branches/ubuntu/vivid/glib2.0/vivid-proposed

For C applications you generally just call <a class="link" href="GAsyncInitable.html#g-async-initable-new-async" title="g_async_initable_new_async ()"><code class="function">g_async_initable_new_async()</code></a>

147

directly, or indirectly via a <code class="function">foo_thing_new_async()</code> wrapper. This will call

148

<a class="link" href="GAsyncInitable.html#g-async-initable-init-async" title="g_async_initable_init_async ()"><code class="function">g_async_initable_init_async()</code></a> under the cover, calling back with <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> and

149

a set <a href="../glib/glib-Error-Reporting.html#GError"><code class="literal">GError</code></a> on failure.

148

<a class="link" href="GAsyncInitable.html#g-async-initable-init-async" title="g_async_initable_init_async ()"><code class="function">g_async_initable_init_async()</code></a> under the cover, calling back with <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> and

149

a set <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><code class="literal">GError</code></a> on failure.

150

A typical implementation might look something like this:

151

152

254

<a href="GTask.html#g-task-return-boolean">g_task_return_boolean</a> (task, TRUE);

255

else

256

<a href="GTask.html#g-task-return-new-error">g_task_return_new_error</a> (task, ...);

257

<a href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a> (task);

257

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a> (task);

258

}

259

260

<a href="../glib/glib-Doubly-Linked-Lists.html#g-list-free">g_list_free</a> (self->priv->init_results);

260

<a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#g-list-free">g_list_free</a> (self->priv->init_results);

261

self->priv->init_results = NULL;

262

}

263

277

{

278

case NOT_INITIALIZED:

279

_foo_get_ready (self);

280

self->priv->init_results = <a href="../glib/glib-Doubly-Linked-Lists.html#g-list-append">g_list_append</a> (self->priv->init_results,

280

self->priv->init_results = <a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#g-list-append">g_list_append</a> (self->priv->init_results,

281

task);

282

self->priv->state = INITIALIZING;

283

break;

284

case INITIALIZING:

285

286

task);

287

break;

288

case INITIALIZED:

290

<a href="GTask.html#g-task-return-new-error">g_task_return_new_error</a> (task, ...);

291

else

292

293

<a href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a> (task);

293

294

break;

295

}

296

}

300

GAsyncResult *result,

301

GError **error)

302

{

303

<a href="../glib/glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a> (<a href="GTask.html#g-task-is-valid">g_task_is_valid</a> (result, initable), FALSE);

303

<a href="http://library.gnome.org/devel/glib/unstable/glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a> (<a href="GTask.html#g-task-is-valid">g_task_is_valid</a> (result, initable), FALSE);

304

305

return <a href="GTask.html#g-task-propagate-boolean">g_task_propagate_boolean</a> (G_TASK (result), error);

306

}

330

<code>int io_priority</code>,

331

<code><a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable</code>,

332

<code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()">GAsyncReadyCallback</a> callback</code>,

333

<code><a href="../glib/glib-Basic-Types.html#gpointer">gpointer</a> user_data</code>);</pre>

333

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer">gpointer</a> user_data</code>);</pre>

334

Starts asynchronous initialization of the object implementing the

335

interface. This must be done before any real use of the object after

336

initial construction. If the object also implements <a class="link" href="GInitable.html" title="GInitable">GInitable</a> you can

341

initialization.

342

Implementations may also support cancellation. If <code>cancellable</code>

343

is not

344

<a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, then initialization can be cancelled by triggering the cancellable

344

<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, then initialization can be cancelled by triggering the cancellable

345

object from another thread. If the operation was cancelled, the error

346

<a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> will be returned. If <code>cancellable</code>

347

is not <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, and

347

is not <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, and

348

the object doesn't support cancellable initialization, the error

349

<a class="link" href="gio-GIOError.html#G-IO-ERROR-NOT-SUPPORTED:CAPS"><code class="literal">G_IO_ERROR_NOT_SUPPORTED</code></a> will be returned.

350

As with <a class="link" href="GInitable.html" title="GInitable">GInitable</a>, if the object is not initialized, or initialization

369

</tr>

370

<tr>

371

<td class="parameter_name">cancellable</td>

372

<td class="parameter_description">optional <a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> object, <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>

372

<td class="parameter_description">optional <a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> object, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>

373

374

</tr>

375

<tr>

388

389

<a name="id-1.4.11.3.10.2.9"></a><h4>Returns</h4>

390

with an error, then all operations on the object except

391

<a href="../gobject/gobject-The-Base-Object-Type.html#g-object-ref"><code class="function">g_object_ref()</code></a> and <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a> are considered to be invalid, and

392

have undefined behaviour. They will often fail with <a href="../glib/glib-Message-Logging.html#g-critical"><code class="function">g_critical()</code></a> or

393

<a href="../glib/glib-Message-Logging.html#g-warning"><code class="function">g_warning()</code></a>, but this must not be relied on.

391

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-ref"><code class="function">g_object_ref()</code></a> and <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a> are considered to be invalid, and

392

have undefined behaviour. They will often fail with <a href="http://library.gnome.org/devel/glib/unstable/glib-Message-Logging.html#g-critical"><code class="function">g_critical()</code></a> or

393

<a href="http://library.gnome.org/devel/glib/unstable/glib-Message-Logging.html#g-warning"><code class="function">g_warning()</code></a>, but this must not be relied on.

394

Implementations of this method must be idempotent: i.e. multiple calls

395

to this function with the same argument should return the same results.

396

Only the first call initializes the object; further calls return the result

408

<hr>

409

410

<a name="g-async-initable-init-finish"></a><h3>g_async_initable_init_finish ()</h3>

411

<pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a>

411

<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean">gboolean</a>

412

g_async_initable_init_finish (<code><a class="link" href="GAsyncInitable.html" title="GAsyncInitable">GAsyncInitable</a> *initable</code>,

413

<code><a class="link" href="GAsyncResult.html" title="GAsyncResult">GAsyncResult</a> *res</code>,

414

<code><a href="../glib/glib-Error-Reporting.html#GError">GError</a> **error</code>);</pre>

414

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError">GError</a> **error</code>);</pre>

415

Finishes asynchronous initialization and returns the result.

416

See <a class="link" href="GAsyncInitable.html#g-async-initable-init-async" title="g_async_initable_init_async ()"><code class="function">g_async_initable_init_async()</code></a>.

417

435

</tr>

436

<tr>

437

<td class="parameter_name">error</td>

438

<td class="parameter_description">a <a href="../glib/glib-Error-Reporting.html#GError">GError</a> location to store the error occurring, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to

438

<td class="parameter_description">a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError">GError</a> location to store the error occurring, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to

439

ignore.</td>

440

441

</tr>

444

</div>

445

446

<a name="id-1.4.11.3.10.3.6"></a><h4>Returns</h4>

447

<a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if successful. If an error has occurred, this function

448

will return <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> and set <code>error</code>

447

<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if successful. If an error has occurred, this function

448

will return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> and set <code>error</code>

449

appropriately if present.

450

451

</div>

455

456

<a name="g-async-initable-new-async"></a><h3>g_async_initable_new_async ()</h3>

457

<pre class="programlisting">void

458

g_async_initable_new_async (<code><a href="../gobject/gobject-Type-Information.html#GType">GType</a> object_type</code>,

458

g_async_initable_new_async (<code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType">GType</a> object_type</code>,

459

<code>int io_priority</code>,

460

<code><a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable</code>,

461

<code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()">GAsyncReadyCallback</a> callback</code>,

462

<code><a href="../glib/glib-Basic-Types.html#gpointer">gpointer</a> user_data</code>,

463

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *first_property_name</code>,

462

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer">gpointer</a> user_data</code>,

463

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *first_property_name</code>,

464

465

Helper function for constructing <a class="link" href="GAsyncInitable.html" title="GAsyncInitable">GAsyncInitable</a> object. This is

466

similar to <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-new"><code class="function">g_object_new()</code></a> but also initializes the object asynchronously.

466

similar to <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-new"><code class="function">g_object_new()</code></a> but also initializes the object asynchronously.

467

When the initialization is finished, <code>callback</code>

468

will be called. You can

469

then call <a class="link" href="GAsyncInitable.html#g-async-initable-new-finish" title="g_async_initable_new_finish ()"><code class="function">g_async_initable_new_finish()</code></a> to get the new object and check

479

<tbody>

480

<tr>

481

<td class="parameter_name">object_type</td>

482

<td class="parameter_description">a <a href="../gobject/gobject-Type-Information.html#GType">GType</a> supporting <a class="link" href="GAsyncInitable.html" title="GAsyncInitable">GAsyncInitable</a>.</td>

482

<td class="parameter_description">a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType">GType</a> supporting <a class="link" href="GAsyncInitable.html" title="GAsyncInitable">GAsyncInitable</a>.</td>

483

484

</tr>

485

<tr>

489

</tr>

490

<tr>

491

<td class="parameter_name">cancellable</td>

492

<td class="parameter_description">optional <a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> object, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>

493

494

</tr>

495

<tr>

505

</tr>

506

<tr>

507

<td class="parameter_name">first_property_name</td>

508

<td class="parameter_description"> the name of the first property, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if no

508

<td class="parameter_description"> the name of the first property, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if no

509

properties. </td>

510

<td class="parameter_annotations">[<acronym title="NULL is ok, both for passing and for returning.">allow-none</acronym>]</td>

511

</tr>

512

<tr>

513

514

<td class="parameter_description">the value of the first property, followed by other property

515

value pairs, and ended by <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</td>

515

value pairs, and ended by <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</td>

516

517

</tr>

518

</tbody>

523

<hr>

524

525

<a name="g-async-initable-new-finish"></a><h3>g_async_initable_new_finish ()</h3>

526

<pre class="programlisting"><a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a> *

526

<pre class="programlisting"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> *

527

g_async_initable_new_finish (<code><a class="link" href="GAsyncInitable.html" title="GAsyncInitable">GAsyncInitable</a> *initable</code>,

528

<code><a class="link" href="GAsyncResult.html" title="GAsyncResult">GAsyncResult</a> *res</code>,

529

<code><a href="../glib/glib-Error-Reporting.html#GError">GError</a> **error</code>);</pre>

529

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError">GError</a> **error</code>);</pre>

530

Finishes the async construction for the various g_async_initable_new

531

calls, returning the created object or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error.

531

calls, returning the created object or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error.

532

533

<a name="id-1.4.11.3.10.5.5"></a><h4>Parameters</h4>

534

550

</tr>

551

<tr>

552

<td class="parameter_name">error</td>

553

<td class="parameter_description">return location for errors, or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore</td>

553

<td class="parameter_description">return location for errors, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore</td>

554

555

</tr>

556

</tbody>

558

</div>

559

560

<a name="id-1.4.11.3.10.5.6"></a><h4>Returns</h4>

561

a newly created <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>,

562

or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. Free with <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a>.

561

a newly created <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>,

562

or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. Free with <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref"><code class="function">g_object_unref()</code></a>.

563

[<acronym title="Override the parsed C type with given type.">type</acronym> GObject.Object][<acronym title="Free data after the code is done.">transfer full</acronym>]

564

</div>

565

Since 2.22

568

569

<a name="g-async-initable-new-valist-async"></a><h3>g_async_initable_new_valist_async ()</h3>

570

<pre class="programlisting">void

571

g_async_initable_new_valist_async (<code><a href="../gobject/gobject-Type-Information.html#GType">GType</a> object_type</code>,

572

<code>const <a href="../glib/glib-Basic-Types.html#gchar">gchar</a> *first_property_name</code>,

571

g_async_initable_new_valist_async (<code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType">GType</a> object_type</code>,

572

<code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar">gchar</a> *first_property_name</code>,

573

<code>va_list var_args</code>,

574

<code>int io_priority</code>,

575

<code><a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable</code>,

576

<code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()">GAsyncReadyCallback</a> callback</code>,

577

<code><a href="../glib/glib-Basic-Types.html#gpointer">gpointer</a> user_data</code>);</pre>

577

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer">gpointer</a> user_data</code>);</pre>

578

Helper function for constructing <a class="link" href="GAsyncInitable.html" title="GAsyncInitable">GAsyncInitable</a> object. This is

579

similar to <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-new-valist"><code class="function">g_object_new_valist()</code></a> but also initializes the object

579

similar to <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-new-valist"><code class="function">g_object_new_valist()</code></a> but also initializes the object

580

asynchronously.

581

When the initialization is finished, <code>callback</code>

582

will be called. You can

593

<tbody>

594

<tr>

595

<td class="parameter_name">object_type</td>

596

597

598

</tr>

599

<tr>

600

<td class="parameter_name">first_property_name</td>

601

<td class="parameter_description">the name of the first property, followed by

602

the value, and other property value pairs, and ended by <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</td>

602

the value, and other property value pairs, and ended by <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</td>

603

604

</tr>

605

<tr>

615

</tr>

616

<tr>

617

<td class="parameter_name">cancellable</td>

618

<td class="parameter_description">optional <a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> object, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>

619

620

</tr>

621

<tr>

638

639

<a name="g-async-initable-newv-async"></a><h3>g_async_initable_newv_async ()</h3>

640

<pre class="programlisting">void

641

g_async_initable_newv_async (<code><a href="../gobject/gobject-Type-Information.html#GType">GType</a> object_type</code>,

642

<code><a href="../glib/glib-Basic-Types.html#guint">guint</a> n_parameters</code>,

643

<code><a href="../gobject/gobject-The-Base-Object-Type.html#GParameter">GParameter</a> *parameters</code>,

641

g_async_initable_newv_async (<code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType">GType</a> object_type</code>,

642

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint">guint</a> n_parameters</code>,

643

<code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GParameter">GParameter</a> *parameters</code>,

644

<code>int io_priority</code>,

645

<code><a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable</code>,

646

<code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()">GAsyncReadyCallback</a> callback</code>,

647

<code><a href="../glib/glib-Basic-Types.html#gpointer">gpointer</a> user_data</code>);</pre>

647

<code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer">gpointer</a> user_data</code>);</pre>

648

Helper function for constructing <a class="link" href="GAsyncInitable.html" title="GAsyncInitable">GAsyncInitable</a> object. This is

649

similar to <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-newv"><code class="function">g_object_newv()</code></a> but also initializes the object asynchronously.

649

similar to <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-newv"><code class="function">g_object_newv()</code></a> but also initializes the object asynchronously.

650

When the initialization is finished, <code>callback</code>

651

will be called. You can

652

662

<tbody>

663

<tr>

664

<td class="parameter_name">object_type</td>

665

666

667

</tr>

668

<tr>

683

</tr>

684

<tr>

685

<td class="parameter_name">cancellable</td>

686

<td class="parameter_description">optional <a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> object, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore.</td>

687

688

</tr>

689

<tr>

741

</colgroup>

742

<tbody>

743

<tr>

744

<td class="struct_member_name"><a href="../gobject/gobject-Type-Information.html#GTypeInterface">GTypeInterface</a> <code><a name="GAsyncInitableIface.g-iface"></a>g_iface</code>;</td>

744

<td class="struct_member_name"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GTypeInterface">GTypeInterface</a> <code><a name="GAsyncInitableIface.g-iface"></a>g_iface</code>;</td>

745

<td class="struct_member_description">The parent interface.</td>

746

747

</tr>

Older »