[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / api / refcountDetails.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="api.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="api.html" title='Python/C API Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="refcounts.html" />
<link rel="parent" href="refcounts.html" />
<link rel="next" href="types.html" />
<meta name='aesop' content='information' />
<title>1.2.1.1 Reference Count Details </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="1.2.1 Reference Counts"
  href="refcounts.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="1.2.1 Reference Counts"
  href="refcounts.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="1.2.2 Types"
  href="types.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="refcounts.html">1.2.1 Reference Counts</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="refcounts.html">1.2.1 Reference Counts</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="types.html">1.2.2 Types</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H3><A NAME="SECTION003211000000000000000"></A><A NAME="refcountDetails"></A>
<BR>
1.2.1.1 Reference Count Details 
</H3>

<P>
The reference count behavior of functions in the Python/C API is best 
explained in terms of <em>ownership of references</em>.  Ownership
pertains to references, never to objects (objects are not owned: they
are always shared).  "Owning a reference" means being responsible for
calling Py_DECREF on it when the reference is no longer needed. 
Ownership can also be transferred, meaning that the code that receives
ownership of the reference then becomes responsible for eventually
decref'ing it by calling <tt class="cfunction">Py_DECREF()</tt> or
<tt class="cfunction">Py_XDECREF()</tt> when it's no longer needed -or passing on
this responsibility (usually to its caller).
When a function passes ownership of a reference on to its caller, the
caller is said to receive a <em>new</em> reference.  When no ownership
is transferred, the caller is said to <em>borrow</em> the reference.
Nothing needs to be done for a borrowed reference.

<P>
Conversely, when a calling function passes it a reference to an 
object, there are two possibilities: the function <em>steals</em> a 
reference to the object, or it does not.  Few functions steal 
references; the two notable exceptions are
<tt class="cfunction">PyList_SetItem()</tt><a id='l2h-12' xml:id='l2h-12'></a> and
<tt class="cfunction">PyTuple_SetItem()</tt><a id='l2h-13' xml:id='l2h-13'></a>, which 
steal a reference to the item (but not to the tuple or list into which
the item is put!).  These functions were designed to steal a reference
because of a common idiom for populating a tuple or list with newly
created objects; for example, the code to create the tuple <code>(1,
2, "three")</code> could look like this (forgetting about error handling for
the moment; a better way to code this is shown below):

<P>
<div class="verbatim"><pre>
PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_FromString("three"));
</pre></div>

<P>
Incidentally, <tt class="cfunction">PyTuple_SetItem()</tt> is the <em>only</em> way to
set tuple items; <tt class="cfunction">PySequence_SetItem()</tt> and
<tt class="cfunction">PyObject_SetItem()</tt> refuse to do this since tuples are an
immutable data type.  You should only use
<tt class="cfunction">PyTuple_SetItem()</tt> for tuples that you are creating
yourself.

<P>
Equivalent code for populating a list can be written using 
<tt class="cfunction">PyList_New()</tt> and <tt class="cfunction">PyList_SetItem()</tt>.  Such code
can also use <tt class="cfunction">PySequence_SetItem()</tt>; this illustrates the
difference between the two (the extra <tt class="cfunction">Py_DECREF()</tt> calls):

<P>
<div class="verbatim"><pre>
PyObject *l, *x;

l = PyList_New(3);
x = PyInt_FromLong(1L);
PySequence_SetItem(l, 0, x); Py_DECREF(x);
x = PyInt_FromLong(2L);
PySequence_SetItem(l, 1, x); Py_DECREF(x);
x = PyString_FromString("three");
PySequence_SetItem(l, 2, x); Py_DECREF(x);
</pre></div>

<P>
You might find it strange that the ``recommended'' approach takes more
code.  However, in practice, you will rarely use these ways of
creating and populating a tuple or list.  There's a generic function,
<tt class="cfunction">Py_BuildValue()</tt>, that can create most common objects from
C values, directed by a <i class="dfn">format string</i>.  For example, the
above two blocks of code could be replaced by the following (which
also takes care of the error checking):

<P>
<div class="verbatim"><pre>
PyObject *t, *l;

t = Py_BuildValue("(iis)", 1, 2, "three");
l = Py_BuildValue("[iis]", 1, 2, "three");
</pre></div>

<P>
It is much more common to use <tt class="cfunction">PyObject_SetItem()</tt> and
friends with items whose references you are only borrowing, like
arguments that were passed in to the function you are writing.  In
that case, their behaviour regarding reference counts is much saner,
since you don't have to increment a reference count so you can give a
reference away (``have it be stolen'').  For example, this function
sets all items of a list (actually, any mutable sequence) to a given
item:

<P>
<div class="verbatim"><pre>
int
set_all(PyObject *target, PyObject *item)
{
    int i, n;

    n = PyObject_Length(target);
    if (n &lt; 0)
        return -1;
    for (i = 0; i &lt; n; i++) {
        if (PyObject_SetItem(target, i, item) &lt; 0)
            return -1;
    }
    return 0;
}
</pre></div>

<P>
The situation is slightly different for function return values.  
While passing a reference to most functions does not change your 
ownership responsibilities for that reference, many functions that 
return a reference to an object give you ownership of the reference.
The reason is simple: in many cases, the returned object is created 
on the fly, and the reference you get is the only reference to the 
object.  Therefore, the generic functions that return object 
references, like <tt class="cfunction">PyObject_GetItem()</tt> and 
<tt class="cfunction">PySequence_GetItem()</tt>, always return a new reference (the
caller becomes the owner of the reference).

<P>
It is important to realize that whether you own a reference returned 
by a function depends on which function you call only -- <em>the
plumage</em> (the type of the object passed as an
argument to the function) <em>doesn't enter into it!</em>  Thus, if you 
extract an item from a list using <tt class="cfunction">PyList_GetItem()</tt>, you
don't own the reference -- but if you obtain the same item from the
same list using <tt class="cfunction">PySequence_GetItem()</tt> (which happens to
take exactly the same arguments), you do own a reference to the
returned object.

<P>
Here is an example of how you could write a function that computes the
sum of the items in a list of integers; once using 
<tt class="cfunction">PyList_GetItem()</tt><a id='l2h-14' xml:id='l2h-14'></a>, and once using
<tt class="cfunction">PySequence_GetItem()</tt><a id='l2h-15' xml:id='l2h-15'></a>.

<P>
<div class="verbatim"><pre>
long
sum_list(PyObject *list)
{
    int i, n;
    long total = 0;
    PyObject *item;

    n = PyList_Size(list);
    if (n &lt; 0)
        return -1; /* Not a list */
    for (i = 0; i &lt; n; i++) {
        item = PyList_GetItem(list, i); /* Can't fail */
        if (!PyInt_Check(item)) continue; /* Skip non-integers */
        total += PyInt_AsLong(item);
    }
    return total;
}
</pre></div>

<P>
<div class="verbatim"><pre>
long
sum_sequence(PyObject *sequence)
{
    int i, n;
    long total = 0;
    PyObject *item;
    n = PySequence_Length(sequence);
    if (n &lt; 0)
        return -1; /* Has no length */
    for (i = 0; i &lt; n; i++) {
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* Not a sequence, or other failure */
        if (PyInt_Check(item))
            total += PyInt_AsLong(item);
        Py_DECREF(item); /* Discard reference ownership */
    }
    return total;
}
</pre></div>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="1.2.1 Reference Counts"
  href="refcounts.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="1.2.1 Reference Counts"
  href="refcounts.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="1.2.2 Types"
  href="types.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="refcounts.html">1.2.1 Reference Counts</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="refcounts.html">1.2.1 Reference Counts</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="types.html">1.2.2 Types</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="api.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="api.html" title='Python/C API Reference Manual' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="prev" href="refcounts.html" />
	13	<link rel="parent" href="refcounts.html" />
	14	<link rel="next" href="types.html" />
	15	<meta name='aesop' content='information' />
	16	<title>1.2.1.1 Reference Count Details </title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="1.2.1 Reference Counts"
	24	href="refcounts.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="1.2.1 Reference Counts"
	27	href="refcounts.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="1.2.2 Types"
	30	href="types.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Python/C API Reference Manual</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><a rel="index" title="Index"
	39	href="genindex.html"><img src='../icons/index.png'
	40	border='0' height='32' alt='Index' width='32' /></A></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="refcounts.html">1.2.1 Reference Counts</A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="refcounts.html">1.2.1 Reference Counts</A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="types.html">1.2.2 Types</A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H3><A NAME="SECTION003211000000000000000"></A><A NAME="refcountDetails"></A>
	55	<BR>
	56	1.2.1.1 Reference Count Details
	57	</H3>
	58
	59	<P>
	60	The reference count behavior of functions in the Python/C API is best
	61	explained in terms of <em>ownership of references</em>. Ownership
	62	pertains to references, never to objects (objects are not owned: they
	63	are always shared). "Owning a reference" means being responsible for
	64	calling Py_DECREF on it when the reference is no longer needed.
65	Ownership can also be transferred, meaning that the code that receives
66	ownership of the reference then becomes responsible for eventually
67	decref'ing it by calling <tt class="cfunction">Py_DECREF()</tt> or
68	<tt class="cfunction">Py_XDECREF()</tt> when it's no longer needed -or passing on
69	this responsibility (usually to its caller).
70	When a function passes ownership of a reference on to its caller, the
71	caller is said to receive a <em>new</em> reference. When no ownership
72	is transferred, the caller is said to <em>borrow</em> the reference.
73	Nothing needs to be done for a borrowed reference.
74
75	<P>
76	Conversely, when a calling function passes it a reference to an
77	object, there are two possibilities: the function <em>steals</em> a
78	reference to the object, or it does not. Few functions steal
79	references; the two notable exceptions are
80	<tt class="cfunction">PyList_SetItem()</tt><a id='l2h-12' xml:id='l2h-12'></a> and
81	<tt class="cfunction">PyTuple_SetItem()</tt><a id='l2h-13' xml:id='l2h-13'></a>, which
82	steal a reference to the item (but not to the tuple or list into which
83	the item is put!). These functions were designed to steal a reference
84	because of a common idiom for populating a tuple or list with newly
85	created objects; for example, the code to create the tuple <code>(1,
86	2, "three")</code> could look like this (forgetting about error handling for
87	the moment; a better way to code this is shown below):
88
89	<P>
90	<div class="verbatim"><pre>
91	PyObject *t;
92
93	t = PyTuple_New(3);
94	PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
95	PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
96	PyTuple_SetItem(t, 2, PyString_FromString("three"));
97	</pre></div>
98
99	<P>
100	Incidentally, <tt class="cfunction">PyTuple_SetItem()</tt> is the <em>only</em> way to
101	set tuple items; <tt class="cfunction">PySequence_SetItem()</tt> and
102	<tt class="cfunction">PyObject_SetItem()</tt> refuse to do this since tuples are an
103	immutable data type. You should only use
104	<tt class="cfunction">PyTuple_SetItem()</tt> for tuples that you are creating
105	yourself.
106
107	<P>
108	Equivalent code for populating a list can be written using
109	<tt class="cfunction">PyList_New()</tt> and <tt class="cfunction">PyList_SetItem()</tt>. Such code
110	can also use <tt class="cfunction">PySequence_SetItem()</tt>; this illustrates the
111	difference between the two (the extra <tt class="cfunction">Py_DECREF()</tt> calls):
112
113	<P>
114	<div class="verbatim"><pre>
115	PyObject l, x;
116
117	l = PyList_New(3);
118	x = PyInt_FromLong(1L);
119	PySequence_SetItem(l, 0, x); Py_DECREF(x);
120	x = PyInt_FromLong(2L);
121	PySequence_SetItem(l, 1, x); Py_DECREF(x);
122	x = PyString_FromString("three");
123	PySequence_SetItem(l, 2, x); Py_DECREF(x);
124	</pre></div>
125
126	<P>
127	You might find it strange that the ``recommended'' approach takes more
128	code. However, in practice, you will rarely use these ways of
129	creating and populating a tuple or list. There's a generic function,
130	<tt class="cfunction">Py_BuildValue()</tt>, that can create most common objects from
131	C values, directed by a <i class="dfn">format string</i>. For example, the
132	above two blocks of code could be replaced by the following (which
133	also takes care of the error checking):
134
135	<P>
136	<div class="verbatim"><pre>
137	PyObject t, l;
138
139	t = Py_BuildValue("(iis)", 1, 2, "three");
140	l = Py_BuildValue("[iis]", 1, 2, "three");
141	</pre></div>
142
143	<P>
144	It is much more common to use <tt class="cfunction">PyObject_SetItem()</tt> and
145	friends with items whose references you are only borrowing, like
146	arguments that were passed in to the function you are writing. In
147	that case, their behaviour regarding reference counts is much saner,
148	since you don't have to increment a reference count so you can give a
149	reference away (``have it be stolen''). For example, this function
150	sets all items of a list (actually, any mutable sequence) to a given
151	item:
152
153	<P>
154	<div class="verbatim"><pre>
155	int
156	set_all(PyObject target, PyObject item)
157	{
158	int i, n;
159
160	n = PyObject_Length(target);
161	if (n < 0)
162	return -1;
163	for (i = 0; i < n; i++) {
164	if (PyObject_SetItem(target, i, item) < 0)
165	return -1;
166	}
167	return 0;
168	}
169	</pre></div>
170
171	<P>
172	The situation is slightly different for function return values.
173	While passing a reference to most functions does not change your
174	ownership responsibilities for that reference, many functions that
175	return a reference to an object give you ownership of the reference.
176	The reason is simple: in many cases, the returned object is created
177	on the fly, and the reference you get is the only reference to the
178	object. Therefore, the generic functions that return object
179	references, like <tt class="cfunction">PyObject_GetItem()</tt> and
180	<tt class="cfunction">PySequence_GetItem()</tt>, always return a new reference (the
181	caller becomes the owner of the reference).
182
183	<P>
184	It is important to realize that whether you own a reference returned
185	by a function depends on which function you call only -- <em>the
186	plumage</em> (the type of the object passed as an
187	argument to the function) <em>doesn't enter into it!</em> Thus, if you
188	extract an item from a list using <tt class="cfunction">PyList_GetItem()</tt>, you
189	don't own the reference -- but if you obtain the same item from the
190	same list using <tt class="cfunction">PySequence_GetItem()</tt> (which happens to
191	take exactly the same arguments), you do own a reference to the
192	returned object.
193
194	<P>
195	Here is an example of how you could write a function that computes the
196	sum of the items in a list of integers; once using
197	<tt class="cfunction">PyList_GetItem()</tt><a id='l2h-14' xml:id='l2h-14'></a>, and once using
198	<tt class="cfunction">PySequence_GetItem()</tt><a id='l2h-15' xml:id='l2h-15'></a>.
199
200	<P>
201	<div class="verbatim"><pre>
202	long
203	sum_list(PyObject *list)
204	{
205	int i, n;
206	long total = 0;
207	PyObject *item;
208
209	n = PyList_Size(list);
210	if (n < 0)
211	return -1; /* Not a list */
212	for (i = 0; i < n; i++) {
213	item = PyList_GetItem(list, i); /* Can't fail */
214	if (!PyInt_Check(item)) continue; /* Skip non-integers */
215	total += PyInt_AsLong(item);
216	}
217	return total;
218	}
219	</pre></div>
220
221	<P>
222	<div class="verbatim"><pre>
223	long
224	sum_sequence(PyObject *sequence)
225	{
226	int i, n;
227	long total = 0;
228	PyObject *item;
229	n = PySequence_Length(sequence);
230	if (n < 0)
231	return -1; /* Has no length */
232	for (i = 0; i < n; i++) {
233	item = PySequence_GetItem(sequence, i);
234	if (item == NULL)
235	return -1; /* Not a sequence, or other failure */
236	if (PyInt_Check(item))
237	total += PyInt_AsLong(item);
238	Py_DECREF(item); /* Discard reference ownership */
239	}
240	return total;
241	}
242	</pre></div>
243
244	<P>
245
246	<DIV CLASS="navigation">
247	<div class='online-navigation'>
248	<p></p><hr />
249	<table align="center" width="100%" cellpadding="0" cellspacing="2">
250	<tr>
251	<td class='online-navigation'><a rel="prev" title="1.2.1 Reference Counts"
252	href="refcounts.html"><img src='../icons/previous.png'
253	border='0' height='32' alt='Previous Page' width='32' /></A></td>
254	<td class='online-navigation'><a rel="parent" title="1.2.1 Reference Counts"
255	href="refcounts.html"><img src='../icons/up.png'
256	border='0' height='32' alt='Up One Level' width='32' /></A></td>
257	<td class='online-navigation'><a rel="next" title="1.2.2 Types"
258	href="types.html"><img src='../icons/next.png'
259	border='0' height='32' alt='Next Page' width='32' /></A></td>
260	<td align="center" width="100%">Python/C API Reference Manual</td>
261	<td class='online-navigation'><a rel="contents" title="Table of Contents"
262	href="contents.html"><img src='../icons/contents.png'
263	border='0' height='32' alt='Contents' width='32' /></A></td>
264	<td class='online-navigation'><img src='../icons/blank.png'
265	border='0' height='32' alt='' width='32' /></td>
266	<td class='online-navigation'><a rel="index" title="Index"
267	href="genindex.html"><img src='../icons/index.png'
268	border='0' height='32' alt='Index' width='32' /></A></td>
269	</tr></table>
270	<div class='online-navigation'>
271	<b class="navlabel">Previous:</b>
272	<a class="sectref" rel="prev" href="refcounts.html">1.2.1 Reference Counts</A>
273	<b class="navlabel">Up:</b>
274	<a class="sectref" rel="parent" href="refcounts.html">1.2.1 Reference Counts</A>
275	<b class="navlabel">Next:</b>
276	<a class="sectref" rel="next" href="types.html">1.2.2 Types</A>
277	</div>
278	</div>
279	<hr />
280	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
281	</DIV>
282	<!--End of Navigation Panel-->
283	<ADDRESS>
284	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
285	</ADDRESS>
286	</BODY>
287	</HTML>