IdentifiantMot de passe
Mot de passe oublié ?Je m'inscris ! (gratuit)
14. C extension API

14. C extension API

This chapter describes the different available C-APIs for numarray based extension modules.

While this chapter describes the numarray-specifics for writing extension modules, a basic understanding of Pythonextension modules is expected. See Python's Extending and Embedding tutorial and the Python/C API.

The numarray C-API has several different facets, and the first three facets each make different tradeoffs between memory use, speed, and ease of use. An additional facet provides backwards compatability with legacy Numeric code. The final facet consists of miscellaneous function calls used to implement and utilize numarray, that were not part of Numeric.

In addition to most of the basic functionality provided by Numeric, these APIs provide access to misaligned, byteswapped, and discontiguous numarrays. Byteswapped arrays arise in the context of portable binary data formats where the byteorder specified by the data format is not the same as the host processor byte order. Misaligned arrays arise in the context of tabular data: files of records where arrays are superimposed on the column formed by a single field in the record. Discontiguous arrays arise from operations which permute the shape and strides of an array, such as reshape.

Numeric compatability
This API provides a reasonable (if not complete) simulation of the Numeric C-API. It is written in terms of the numarray high level API (discussed below) so that misbehaved numarrays are copied prior to processing with legacy Numeric code. This API was actually written last because of the extra considerations in numarray not found in Numeric. Nevertheless, it is perhaps the most important because it enables writing extension modules which can be compiled for either numarray or Numeric. It is also very useful for porting existing Numeric code. See section 14.3.
This is the cleanest and eaisiest to use API. It creates temporary arrays to handle difficult cases (discontiguous, byteswapped, misaligned) in C code. Code using this API is written in terms of a pointer to a contiguous 1D array of C data. See section 14.4.
This API handles misbehaved arrays without creating temporaries. Code using this API is written to access single elements of an array via macros or functions. Note: These macros are relatively slow compared to raw access to C data, and the functions even slower. See section 14.5.
Code using this API get/sets consecutive elements of the inner dimension of an array, enabling the API to factor out tests for aligment and byteswapping to one test per array rather than one test per element. Fewer tests means better performance, but at a cost of some temporary data and more difficult usage. See section 14.6.
New numarray functions
This last facet of the C-API consists of function calls which have been added to numarray which are orthogonal to each of the 3 native access APIs and not part of the original Numeric. See section 14.7

Send comments to the NumArray community.