docs/html/object-model-lifecycle.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>Object lifecycle management: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="object-model.html" title="The HarfBuzz object model">
   9 <link rel="prev" href="object-model-object-types.html" title="Objects in HarfBuzz">
  10 <link rel="next" href="object-model-user-data.html" title="User data">
  11 <meta name="generator" content="GTK-Doc V1.32.1 (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="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="object-model.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="object-model-object-types.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="object-model-user-data.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="section">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="object-model-lifecycle"></a>Object lifecycle management</h2></div></div></div>
  25 <p>
  26       Each object type in HarfBuzz provides a
  27       <code class="function">create()</code> method. Some object types provide
  28       additional variants of <code class="function">create()</code> to handle
  29       special cases or to speed up common tasks; those variants are
  30       documented in the API reference. For example,
  31       <code class="function">hb_blob_create_from_file()</code> constructs a new
  32       blob directly from the contents of a file.
  33     </p>
  34 <p>
  35       All objects are created with an initial reference count of
  36       <code class="literal">1</code>. Client programs can increase the reference
  37       count on an object by calling its
  38       <code class="function">reference()</code> method. Whenever a client
  39       program is finished with an object, it should call its
  40       corresponding <code class="function">destroy()</code> method. The destroy
  41       method will decrease the reference count on the object and,
  42       whenever the reference count reaches zero, it will also destroy
  43       the object and free all of the associated memory.
  44     </p>
  45 <p>
  46       All of HarfBuzz's object-lifecycle-management APIs are
  47       thread-safe (unless you compiled HarfBuzz from source with the
  48       <code class="literal">HB_NO_MT</code> configuration flag), even when the
  49       object as a whole is not thread-safe.
  50       It is also permissible to <code class="function">reference()</code> or to
  51       <code class="function">destroy()</code> the <code class="literal">NULL</code>
  52       value.
  53     </p>
  54 <p>
  55       Some objects are thread-safe after they have been constructed
  56       and set up. The general pattern is to
  57       <code class="function">create()</code> the object, make a few
  58       <code class="function">set_*()</code> calls to set up the
  59       object, and then use it without further modification.
  60     </p>
  61 <p>
  62       To ensure that such an object is not modified, client programs
  63       can explicitly mark an object as immutable. HarfBuzz provides
  64       <code class="function">make_immutable()</code> methods to mark an object
  65       as immutable and <code class="function">is_immutable()</code> methods to
  66       test whether or not an object is immutable. Attempts to use
  67       setter functions on immutable objects will fail silently; see the API
  68       Reference manual for specifics.
  69     </p>
  70 <p>
  71       Note also that there are no "make mutable" methods. If client
  72       programs need to alter an object previously marked as immutable,
  73       they will need to make a duplicate of the original.
  74     </p>
  75 <p>
  76       Finally, object constructors (and, indeed, as much of the
  77       shaping API as possible) will never return
  78       <code class="literal">NULL</code>.  Instead, if there is an allocation
  79       error, each constructor will return an “empty” object
  80       singleton.
  81     </p>
  82 <p>
  83       These empty-object singletons are inert and safe (although
  84       typically useless) to pass around.  This design choice avoids
  85       having to check for <code class="literal">NULL</code> pointers all
  86       throughout the code.
  87     </p>
  88 <p>
  89       In addition, this “empty” object singleton can also be accessed
  90       using the <code class="function">get_empty()</code> method of the object
  91       type in question.
  92     </p>
  93 </div>
  94 <div class="footer">
  95 <hr>Generated by GTK-Doc V1.32.1</div>
  96 </body>
  97 </html>