[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / api / buffer-structs.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="next" href="supporting-iteration.html" />
<link rel="prev" href="sequence-structs.html" />
<link rel="parent" href="newTypes.html" />
<link rel="next" href="supporting-iteration.html" />
<meta name='aesop' content='information' />
<title>10.7 Buffer Object Structures </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="10.6 Sequence Object Structures"
  href="sequence-structs.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="10. Object Implementation Support"
  href="newTypes.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="10.8 Supporting the Iterator"
  href="supporting-iteration.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="sequence-structs.html">10.6 Sequence Object Structures</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="supporting-iteration.html">10.8 Supporting the Iterator</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0012700000000000000000"></A><A NAME="buffer-structs"></A>
<BR>
10.7 Buffer Object Structures 
</H1>

<P>
The buffer interface exports a model where an object can expose its
internal data as a set of chunks of data, where each chunk is
specified as a pointer/length pair.  These chunks are called
<i class="dfn">segments</i> and are presumed to be non-contiguous in memory.

<P>
If an object does not export the buffer interface, then its
<tt class="member">tp_as_buffer</tt> member in the <tt class="ctype">PyTypeObject</tt> structure
should be <tt class="constant">NULL</tt>.  Otherwise, the <tt class="member">tp_as_buffer</tt> will point to
a <tt class="ctype">PyBufferProcs</tt> structure.

<P>
<span class="note"><b class="label">Note:</b>
It is very important that your <tt class="ctype">PyTypeObject</tt> structure
uses <tt class="constant">Py_TPFLAGS_DEFAULT</tt> for the value of the
<tt class="member">tp_flags</tt> member rather than <code>0</code>.  This tells the Python
runtime that your <tt class="ctype">PyBufferProcs</tt> structure contains the
<tt class="member">bf_getcharbuffer</tt> slot. Older versions of Python did not have
this member, so a new Python interpreter using an old extension needs
to be able to test for its presence before using it.</span>

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-1008' xml:id='l2h-1008'>PyBufferProcs</a></tt></b></dt>
<dd>
  Structure used to hold the function pointers which define an
  implementation of the buffer protocol.

<P>
The first slot is <tt class="member">bf_getreadbuffer</tt>, of type
  <tt class="ctype">getreadbufferproc</tt>.  If this slot is <tt class="constant">NULL</tt>, then the object
  does not support reading from the internal data.  This is
  non-sensical, so implementors should fill this in, but callers
  should test that the slot contains a non-<tt class="constant">NULL</tt> value.

<P>
The next slot is <tt class="member">bf_getwritebuffer</tt> having type
  <tt class="ctype">getwritebufferproc</tt>.  This slot may be <tt class="constant">NULL</tt> if the object
  does not allow writing into its returned buffers.

<P>
The third slot is <tt class="member">bf_getsegcount</tt>, with type
  <tt class="ctype">getsegcountproc</tt>.  This slot must not be <tt class="constant">NULL</tt> and is used
  to inform the caller how many segments the object contains.  Simple
  objects such as <tt class="ctype">PyString_Type</tt> and <tt class="ctype">PyBuffer_Type</tt>
  objects contain a single segment.

<P>
The last slot is <tt class="member">bf_getcharbuffer</tt>, of type
  <tt class="ctype">getcharbufferproc</tt>.  This slot will only be present if the
  <tt class="constant">Py_TPFLAGS_HAVE_GETCHARBUFFER</tt> flag is present in the
  <tt class="member">tp_flags</tt> field of the object's <tt class="ctype">PyTypeObject</tt>.
  Before using this slot, the caller should test whether it is present
  by using the
  <tt class="cfunction">PyType_HasFeature()</tt><a id='l2h-1014' xml:id='l2h-1014'></a>
  function.  If present, it may be <tt class="constant">NULL</tt>, indicating that the object's
  contents cannot be used as <em>8-bit characters</em>.
  The slot function may also raise an error if the object's contents
  cannot be interpreted as 8-bit characters.  For example, if the
  object is an array which is configured to hold floating point
  values, an exception may be raised if a caller attempts to use
  <tt class="member">bf_getcharbuffer</tt> to fetch a sequence of 8-bit characters.
  This notion of exporting the internal buffers as ``text'' is used to
  distinguish between objects that are binary in nature, and those
  which have character-based content.

<P>
<span class="note"><b class="label">Note:</b>
The current policy seems to state that these characters
  may be multi-byte characters. This implies that a buffer size of
  <var>N</var> does not mean there are <var>N</var> characters present.</span>
</dl>

<P>
<dl><dt><b><tt id='l2h-1009' xml:id='l2h-1009'>Py_TPFLAGS_HAVE_GETCHARBUFFER</tt></b></dt>
<dd>
  Flag bit set in the type structure to indicate that the
  <tt class="member">bf_getcharbuffer</tt> slot is known.  This being set does not
  indicate that the object supports the buffer interface or that the
  <tt class="member">bf_getcharbuffer</tt> slot is non-<tt class="constant">NULL</tt>.
</dd></dl>

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-1010' xml:id='l2h-1010'>int (*getreadbufferproc)
                            (PyObject *self, int segment, void **ptrptr)</a></tt></b></dt>
<dd>
  Return a pointer to a readable segment of the buffer.  This function
  is allowed to raise an exception, in which case it must return
  <code>-1</code>.  The <var>segment</var> which is passed must be zero or
  positive, and strictly less than the number of segments returned by
  the <tt class="member">bf_getsegcount</tt> slot function.  On success, it returns
  the length of the buffer memory, and sets <code>*<var>ptrptr</var></code> to a
  pointer to that memory.
</dl>

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-1011' xml:id='l2h-1011'>int (*getwritebufferproc)
                            (PyObject *self, int segment, void **ptrptr)</a></tt></b></dt>
<dd>
  Return a pointer to a writable memory buffer in
  <code>*<var>ptrptr</var></code>, and the length of that segment as the function
  return value.  The memory buffer must correspond to buffer segment
  <var>segment</var>.  Must return <code>-1</code> and set an exception on
  error.  <tt class="exception">TypeError</tt> should be raised if the object only
  supports read-only buffers, and <tt class="exception">SystemError</tt> should be
  raised when <var>segment</var> specifies a segment that doesn't exist.
</dl>

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-1012' xml:id='l2h-1012'>int (*getsegcountproc)
                            (PyObject *self, int *lenp)</a></tt></b></dt>
<dd>
  Return the number of memory segments which comprise the buffer.  If
  <var>lenp</var> is not <tt class="constant">NULL</tt>, the implementation must report the sum of
  the sizes (in bytes) of all segments in <code>*<var>lenp</var></code>.
  The function cannot fail.
</dl>

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-1013' xml:id='l2h-1013'>int (*getcharbufferproc)
                            (PyObject *self, int segment, const char **ptrptr)</a></tt></b></dt>
<dd>
  Return the size of the memory buffer in <var>ptrptr</var> for segment
  <var>segment</var>.  <code>*<var>ptrptr</var></code> is set to the memory buffer.
</dl>

<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="10.6 Sequence Object Structures"
  href="sequence-structs.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="10. Object Implementation Support"
  href="newTypes.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="10.8 Supporting the Iterator"
  href="supporting-iteration.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="sequence-structs.html">10.6 Sequence Object Structures</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="supporting-iteration.html">10.8 Supporting the Iterator</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="next" href="supporting-iteration.html" />
	13	<link rel="prev" href="sequence-structs.html" />
	14	<link rel="parent" href="newTypes.html" />
	15	<link rel="next" href="supporting-iteration.html" />
	16	<meta name='aesop' content='information' />
	17	<title>10.7 Buffer Object Structures </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="10.6 Sequence Object Structures"
	25	href="sequence-structs.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="10. Object Implementation Support"
	28	href="newTypes.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="10.8 Supporting the Iterator"
	31	href="supporting-iteration.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python/C API Reference Manual</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="sequence-structs.html">10.6 Sequence Object Structures</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="supporting-iteration.html">10.8 Supporting the Iterator</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION0012700000000000000000"></A><A NAME="buffer-structs"></A>
	56	<BR>
	57	10.7 Buffer Object Structures
	58	</H1>
	59
	60	<P>
	61	The buffer interface exports a model where an object can expose its
	62	internal data as a set of chunks of data, where each chunk is
	63	specified as a pointer/length pair. These chunks are called
	64	<i class="dfn">segments</i> and are presumed to be non-contiguous in memory.
65
66	<P>
67	If an object does not export the buffer interface, then its
68	<tt class="member">tp_as_buffer</tt> member in the <tt class="ctype">PyTypeObject</tt> structure
69	should be <tt class="constant">NULL</tt>. Otherwise, the <tt class="member">tp_as_buffer</tt> will point to
70	a <tt class="ctype">PyBufferProcs</tt> structure.
71
72	<P>
73	<span class="note"><b class="label">Note:</b>
74	It is very important that your <tt class="ctype">PyTypeObject</tt> structure
75	uses <tt class="constant">Py_TPFLAGS_DEFAULT</tt> for the value of the
76	<tt class="member">tp_flags</tt> member rather than <code>0</code>. This tells the Python
77	runtime that your <tt class="ctype">PyBufferProcs</tt> structure contains the
78	<tt class="member">bf_getcharbuffer</tt> slot. Older versions of Python did not have
79	this member, so a new Python interpreter using an old extension needs
80	to be able to test for its presence before using it.</span>
81
82	<P>
83	<dl><dt><b><tt class="ctype"><a id='l2h-1008' xml:id='l2h-1008'>PyBufferProcs</a></tt></b></dt>
84	<dd>
85	Structure used to hold the function pointers which define an
86	implementation of the buffer protocol.
87
88	<P>
89	The first slot is <tt class="member">bf_getreadbuffer</tt>, of type
90	<tt class="ctype">getreadbufferproc</tt>. If this slot is <tt class="constant">NULL</tt>, then the object
91	does not support reading from the internal data. This is
92	non-sensical, so implementors should fill this in, but callers
93	should test that the slot contains a non-<tt class="constant">NULL</tt> value.
94
95	<P>
96	The next slot is <tt class="member">bf_getwritebuffer</tt> having type
97	<tt class="ctype">getwritebufferproc</tt>. This slot may be <tt class="constant">NULL</tt> if the object
98	does not allow writing into its returned buffers.
99
100	<P>
101	The third slot is <tt class="member">bf_getsegcount</tt>, with type
102	<tt class="ctype">getsegcountproc</tt>. This slot must not be <tt class="constant">NULL</tt> and is used
103	to inform the caller how many segments the object contains. Simple
104	objects such as <tt class="ctype">PyString_Type</tt> and <tt class="ctype">PyBuffer_Type</tt>
105	objects contain a single segment.
106
107	<P>
108	The last slot is <tt class="member">bf_getcharbuffer</tt>, of type
109	<tt class="ctype">getcharbufferproc</tt>. This slot will only be present if the
110	<tt class="constant">Py_TPFLAGS_HAVE_GETCHARBUFFER</tt> flag is present in the
111	<tt class="member">tp_flags</tt> field of the object's <tt class="ctype">PyTypeObject</tt>.
112	Before using this slot, the caller should test whether it is present
113	by using the
114	<tt class="cfunction">PyType_HasFeature()</tt><a id='l2h-1014' xml:id='l2h-1014'></a>
115	function. If present, it may be <tt class="constant">NULL</tt>, indicating that the object's
116	contents cannot be used as <em>8-bit characters</em>.
117	The slot function may also raise an error if the object's contents
118	cannot be interpreted as 8-bit characters. For example, if the
119	object is an array which is configured to hold floating point
120	values, an exception may be raised if a caller attempts to use
121	<tt class="member">bf_getcharbuffer</tt> to fetch a sequence of 8-bit characters.
122	This notion of exporting the internal buffers as ``text'' is used to
123	distinguish between objects that are binary in nature, and those
124	which have character-based content.
125
126	<P>
127	<span class="note"><b class="label">Note:</b>
128	The current policy seems to state that these characters
129	may be multi-byte characters. This implies that a buffer size of
130	<var>N</var> does not mean there are <var>N</var> characters present.</span>
131	</dl>
132
133	<P>
134	<dl><dt><b><tt id='l2h-1009' xml:id='l2h-1009'>Py_TPFLAGS_HAVE_GETCHARBUFFER</tt></b></dt>
135	<dd>
136	Flag bit set in the type structure to indicate that the
137	<tt class="member">bf_getcharbuffer</tt> slot is known. This being set does not
138	indicate that the object supports the buffer interface or that the
139	<tt class="member">bf_getcharbuffer</tt> slot is non-<tt class="constant">NULL</tt>.
140	</dd></dl>
141
142	<P>
143	<dl><dt><b><tt class="ctype"><a id='l2h-1010' xml:id='l2h-1010'>int (*getreadbufferproc)
144	(PyObject self, int segment, void *ptrptr)</a></tt></b></dt>
145	<dd>
146	Return a pointer to a readable segment of the buffer. This function
147	is allowed to raise an exception, in which case it must return
148	<code>-1</code>. The <var>segment</var> which is passed must be zero or
149	positive, and strictly less than the number of segments returned by
150	the <tt class="member">bf_getsegcount</tt> slot function. On success, it returns
151	the length of the buffer memory, and sets <code>*<var>ptrptr</var></code> to a
152	pointer to that memory.
153	</dl>
154
155	<P>
156	<dl><dt><b><tt class="ctype"><a id='l2h-1011' xml:id='l2h-1011'>int (*getwritebufferproc)
157	(PyObject self, int segment, void *ptrptr)</a></tt></b></dt>
158	<dd>
159	Return a pointer to a writable memory buffer in
160	<code>*<var>ptrptr</var></code>, and the length of that segment as the function
161	return value. The memory buffer must correspond to buffer segment
162	<var>segment</var>. Must return <code>-1</code> and set an exception on
163	error. <tt class="exception">TypeError</tt> should be raised if the object only
164	supports read-only buffers, and <tt class="exception">SystemError</tt> should be
165	raised when <var>segment</var> specifies a segment that doesn't exist.
166	</dl>
167
168	<P>
169	<dl><dt><b><tt class="ctype"><a id='l2h-1012' xml:id='l2h-1012'>int (*getsegcountproc)
170	(PyObject self, int lenp)</a></tt></b></dt>
171	<dd>
172	Return the number of memory segments which comprise the buffer. If
173	<var>lenp</var> is not <tt class="constant">NULL</tt>, the implementation must report the sum of
174	the sizes (in bytes) of all segments in <code>*<var>lenp</var></code>.
175	The function cannot fail.
176	</dl>
177
178	<P>
179	<dl><dt><b><tt class="ctype"><a id='l2h-1013' xml:id='l2h-1013'>int (*getcharbufferproc)
180	(PyObject self, int segment, const char *ptrptr)</a></tt></b></dt>
181	<dd>
182	Return the size of the memory buffer in <var>ptrptr</var> for segment
183	<var>segment</var>. <code>*<var>ptrptr</var></code> is set to the memory buffer.
184	</dl>
185
186	<P>
187
188	<DIV CLASS="navigation">
189	<div class='online-navigation'>
190	<p></p><hr />
191	<table align="center" width="100%" cellpadding="0" cellspacing="2">
192	<tr>
193	<td class='online-navigation'><a rel="prev" title="10.6 Sequence Object Structures"
194	href="sequence-structs.html"><img src='../icons/previous.png'
195	border='0' height='32' alt='Previous Page' width='32' /></A></td>
196	<td class='online-navigation'><a rel="parent" title="10. Object Implementation Support"
197	href="newTypes.html"><img src='../icons/up.png'
198	border='0' height='32' alt='Up One Level' width='32' /></A></td>
199	<td class='online-navigation'><a rel="next" title="10.8 Supporting the Iterator"
200	href="supporting-iteration.html"><img src='../icons/next.png'
201	border='0' height='32' alt='Next Page' width='32' /></A></td>
202	<td align="center" width="100%">Python/C API Reference Manual</td>
203	<td class='online-navigation'><a rel="contents" title="Table of Contents"
204	href="contents.html"><img src='../icons/contents.png'
205	border='0' height='32' alt='Contents' width='32' /></A></td>
206	<td class='online-navigation'><img src='../icons/blank.png'
207	border='0' height='32' alt='' width='32' /></td>
208	<td class='online-navigation'><a rel="index" title="Index"
209	href="genindex.html"><img src='../icons/index.png'
210	border='0' height='32' alt='Index' width='32' /></A></td>
211	</tr></table>
212	<div class='online-navigation'>
213	<b class="navlabel">Previous:</b>
214	<a class="sectref" rel="prev" href="sequence-structs.html">10.6 Sequence Object Structures</A>
215	<b class="navlabel">Up:</b>
216	<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
217	<b class="navlabel">Next:</b>
218	<a class="sectref" rel="next" href="supporting-iteration.html">10.8 Supporting the Iterator</A>
219	</div>
220	</div>
221	<hr />
222	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
223	</DIV>
224	<!--End of Navigation Panel-->
225	<ADDRESS>
226	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
227	</ADDRESS>
228	</BODY>
229	</HTML>