← Back to branch summary

~ubuntu-branches/ubuntu/hoary/orbit2/hoary

« back to all changes in this revision

Viewing changes to docs/api/xml/orbit2-allocators.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2005-02-06 12:48:25 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20050206124825-gatccsi77chbn92e
Tags: 1:2.12.1-0ubuntu1
* New upstream release.
* debian/patches/100-compile-name-server.patch:
  - updated.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/api/xml/orbit2-allocators.xml
 
1
<refentry id="ORBit2-orbit2-allocators">
 
2
<refmeta>
 
3
<refentrytitle>Allocators</refentrytitle>
 
4
<manvolnum>3</manvolnum>
 
5
<refmiscinfo>ORBIT2 Library</refmiscinfo>
 
6
</refmeta>
 
7
 
 
8
<refnamediv>
 
9
<refname>Allocators</refname><refpurpose>Memory allocation functions for CORBA types.</refpurpose>
 
10
</refnamediv>
 
11
 
 
12
<refsynopsisdiv><title>Synopsis</title>
 
13
 
 
14
<synopsis>
 
15
 
 
16
 
 
17
 
 
18
#define     <link linkend="CORBA-sequence-set-release">CORBA_sequence_set_release</link>      (s,r)
 
19
#define     <link linkend="CORBA-sequence-get-release">CORBA_sequence_get_release</link>      (s)
 
20
<link linkend="void">void</link>        <link linkend="CORBA-free">CORBA_free</link>                      (<link linkend="gpointer">gpointer</link> mem);
 
21
<link linkend="gpointer">gpointer</link>    <link linkend="ORBit-alloc-tcval">ORBit_alloc_tcval</link>               (<link linkend="CORBA-TypeCode">CORBA_TypeCode</link> tc,
 
22
                                             <link linkend="guint">guint</link> nelements);
 
23
<link linkend="gpointer">gpointer</link>    <link linkend="ORBit-realloc-tcval">ORBit_realloc_tcval</link>             (<link linkend="gpointer">gpointer</link> old,
 
24
                                             <link linkend="CORBA-TypeCode">CORBA_TypeCode</link> tc,
 
25
                                             <link linkend="guint">guint</link> old_num_elements,
 
26
                                             <link linkend="guint">guint</link> num_elements);
 
27
 
 
28
</synopsis>
 
29
</refsynopsisdiv>
 
30
 
 
31
 
 
32
 
 
33
 
 
34
 
 
35
 
 
36
 
 
37
 
 
38
 
 
39
<refsect1>
 
40
<title>Description</title>
 
41
<para>
 
42
 
 
43
</para>
 
44
</refsect1>
 
45
 
 
46
<refsect1>
 
47
<title>Details</title>
 
48
<refsect2>
 
49
<title><anchor id="CORBA-sequence-set-release"/>CORBA_sequence_set_release()</title>
 
50
<indexterm><primary>CORBA_sequence_set_release</primary></indexterm><programlisting>#define CORBA_sequence_set_release(s,r) (s)-&gt;_release = r
 
51
</programlisting>
 
52
<para>
 
53
    <link linkend="CORBA-sequence-set-release"><function>CORBA_sequence_set_release()</function></link> can be used to set the state of the
 
54
    release flag. If the flag is set to <literal>TRUE</literal>, the sequence effectively
 
55
    "owns" the storage pointed to by <structfield>_buffer</structfield>; if
 
56
    <literal>FALSE</literal>, the programmer is responsible for the storage. If, for
 
57
    example, a sequence is returned from an operation with its release
 
58
    flag set to <literal>FALSE</literal>, calling <link linkend="CORBA-free"><function>CORBA_free()</function></link> on the returned sequence
 
59
    pointer will not deallocate the memory pointed to by
 
60
    <structfield>_buffer</structfield>.
 
61
</para>
 
62
<para>
 
63
    Also, passing a null pointer or a pointer to something other than
 
64
    a sequence type to either <link linkend="CORBA-sequence-set-release"><function>CORBA_sequence_set_release()</function></link> or
 
65
    <link linkend="CORBA-sequence-get-release"><function>CORBA_sequence_get_release()</function></link> produces undefined behavior.
 
66
</para>
 
67
<para>
 
68
    <link linkend="CORBA-sequence-set-release"><function>CORBA_sequence_set_release()</function></link> should only be used by the creator of a
 
69
    sequence. If it is not called for a given sequence instance, then
 
70
    the default value of the release flag for that instance is <literal>FALSE</literal>.
 
71
</para><variablelist role="params">
 
72
<varlistentry><term><parameter>s</parameter>&nbsp;:</term>
 
73
<listitem><simpara>a CORBA sequence
 
74
</simpara></listitem></varlistentry>
 
75
<varlistentry><term><parameter>r</parameter>&nbsp;:</term>
 
76
<listitem><simpara>the new value of the release flag
 
77
 
 
78
 
 
79
</simpara></listitem></varlistentry>
 
80
</variablelist></refsect2>
 
81
<refsect2>
 
82
<title><anchor id="CORBA-sequence-get-release"/>CORBA_sequence_get_release()</title>
 
83
<indexterm><primary>CORBA_sequence_get_release</primary></indexterm><programlisting>#define CORBA_sequence_get_release(s) (s)-&gt;_release
 
84
</programlisting>
 
85
<para>
 
86
    Before calling <link linkend="CORBA-free"><function>CORBA_free()</function></link> on the
 
87
    <structfield>_buffer</structfield> member of a sequence directly,
 
88
    the programmer should check the release flag using
 
89
    <link linkend="CORBA-sequence-get-release"><function>CORBA_sequence_get_release()</function></link>. If it returns <literal>FALSE</literal>, the programmer
 
90
    should not invoke <link linkend="CORBA-free"><function>CORBA_free()</function></link> on the
 
91
    <structfield>_buffer</structfield> member; doing so produces
 
92
    undefined behavior.
 
93
</para><variablelist role="params">
 
94
<varlistentry><term><parameter>s</parameter>&nbsp;:</term>
 
95
<listitem><simpara>a CORBA sequence
 
96
 
 
97
 
 
98
</simpara></listitem></varlistentry>
 
99
</variablelist></refsect2>
 
100
<refsect2>
 
101
<title><anchor id="CORBA-free"/>CORBA_free ()</title>
 
102
<indexterm><primary>CORBA_free</primary></indexterm><programlisting><link linkend="void">void</link>        CORBA_free                      (<link linkend="gpointer">gpointer</link> mem);</programlisting>
 
103
<para>
 
104
    This function should be used to free memory that has been
 
105
    previously allocated with any CORBA memory allocation function.
 
106
    It does deep/recursive/intelligent deallocation of memory,
 
107
    including deallocation of values of <type>CORBA_any</type> types,
 
108
    sequence buffers and elements, etc.
 
109
</para><variablelist role="params">
 
110
<varlistentry><term><parameter>mem</parameter>&nbsp;:</term>
 
111
<listitem><simpara>pointer to any memory block allocated by CORBA/ORBit
 
112
 
 
113
 
 
114
</simpara></listitem></varlistentry>
 
115
</variablelist></refsect2>
 
116
<refsect2>
 
117
<title><anchor id="ORBit-alloc-tcval"/>ORBit_alloc_tcval ()</title>
 
118
<indexterm><primary>ORBit_alloc_tcval</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>    ORBit_alloc_tcval               (<link linkend="CORBA-TypeCode">CORBA_TypeCode</link> tc,
 
119
                                             <link linkend="guint">guint</link> nelements);</programlisting>
 
120
<para>
 
121
    Allocates a memory buffer that can hold <parameter>nelemems</parameter> elements of type <parameter>tc</parameter>.
 
122
</para><variablelist role="params">
 
123
<varlistentry><term><parameter>tc</parameter>&nbsp;:</term>
 
124
<listitem><simpara>typecode of the elements of the array
 
125
</simpara></listitem></varlistentry>
 
126
<varlistentry><term><parameter>nelements</parameter>&nbsp;:</term>
 
127
<listitem><simpara>number of elements of the array
 
128
</simpara></listitem></varlistentry>
 
129
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the address of the newly allocated memory buffer
 
130
 
 
131
 
 
132
</simpara></listitem></varlistentry>
 
133
</variablelist></refsect2>
 
134
<refsect2>
 
135
<title><anchor id="ORBit-realloc-tcval"/>ORBit_realloc_tcval ()</title>
 
136
<indexterm><primary>ORBit_realloc_tcval</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>    ORBit_realloc_tcval             (<link linkend="gpointer">gpointer</link> old,
 
137
                                             <link linkend="CORBA-TypeCode">CORBA_TypeCode</link> tc,
 
138
                                             <link linkend="guint">guint</link> old_num_elements,
 
139
                                             <link linkend="guint">guint</link> num_elements);</programlisting>
 
140
<para>
 
141
    Changes the size of a CORBA memory buffer.
 
142
</para><variablelist role="params">
 
143
<varlistentry><term><parameter>old</parameter>&nbsp;:</term>
 
144
<listitem><simpara>old memory segment, possibly allocated by <link linkend="ORBit-alloc-tcval"><function>ORBit_alloc_tcval()</function></link>
 
145
</simpara></listitem></varlistentry>
 
146
<varlistentry><term><parameter>tc</parameter>&nbsp;:</term>
 
147
<listitem><simpara>typecode of the elements of the array
 
148
</simpara></listitem></varlistentry>
 
149
<varlistentry><term><parameter>old_num_elements</parameter>&nbsp;:</term>
 
150
<listitem><simpara>current number of elements of the array
 
151
</simpara></listitem></varlistentry>
 
152
<varlistentry><term><parameter>num_elements</parameter>&nbsp;:</term>
 
153
<listitem><simpara>new desired size of the array
 
154
</simpara></listitem></varlistentry>
 
155
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the new location of the array
 
156
 
 
157
 
 
158
</simpara></listitem></varlistentry>
 
159
</variablelist></refsect2>
 
160
 
 
161
</refsect1>
 
162
 
 
163
 
 
164
 
 
165
 
 
166
</refentry>