@@@ py_buffer/freebin wip

[catacomb-python] / pyke / pyke.h

/* -*-c-*-
 *
 * Pyke: the Python Kit for Extensions
 *
 * (c) 2019 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Pyke: the Python Kit for Extensions.
 *
 * Pyke is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 2 of the License, or (at your
 * option) any later version.
 *
 * Pyke is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Pyke.  If not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef PYKE_H
#define PYKE_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#define PY_SSIZE_T_CLEAN

#include <Python.h>
#include <structmember.h>

/*----- Other preliminaries -----------------------------------------------*/

#define NOTHING
#define COMMA ,

/*----- Symbol visibility -------------------------------------------------*
 *
 * This library is very messy regarding symbol namespace.  Keep this mess
 * within our shared-object.
 */

#define GOBBLE_SEMI extern int notexist
#if defined(__GNUC__) && defined(__ELF__)
#  define PRIVATE_SYMBOLS _Pragma("GCC visibility push(hidden)") GOBBLE_SEMI
#  define PUBLIC_SYMBOLS _Pragma("GCC visibility pop") GOBBLE_SEMI
#  define EXPORT __attribute__((__visibility__("default")))
#else
#  define PRIVATE_SYMBOLS GOBBLE_SEMI
#  define PUBLIC_SYMBOLS GOBBLE_SEMI
#  define EXPORT
#endif

PRIVATE_SYMBOLS;

/*----- Python version compatibility hacks --------------------------------*/

/* Explicit version switching. */
#if PY_VERSION_HEX >= 0x03000000
#  define PY3 1
#  define PY23(two, three) three
#else
#  define PY2 1
#  define PY23(two, three) two
#endif

/* The handy `Py_TYPE' and `Py_SIZE' macros turned up in 2.6.  Define them if
 * they're not already here.
 */
#ifndef Py_TYPE
#  define Py_TYPE(obj) (((PyObject *)(obj))->ob_type)
#endif
#ifndef Py_SIZE
#  define Py_SIZE(obj) (((PyVarObject *)(obj))->ob_size)
#endif

/* Python 3 added internal structure to the various object headers, and
 * defined a new macro `PyVarObject_HEAD_INIT' to initialize variable-length
 * static instances correctly.  Define it if it's not already here.
 */
#ifndef PyVarObject_HEAD_INIT
#  define PyVarObject_HEAD_INIT(super, sz) PyObject_HEAD_INIT(super) sz,
#endif

/* Python 3 doesn't have `int', only `long', even though it's called `int' at
 * the Python level.  Provide some obvious macros to fill in the gaps.
 */
#ifdef PY3
#  define PyInt_Check PyLong_Check
#  define PyInt_FromLong PyLong_FromLong
#  define PyInt_AS_LONG PyLong_AS_LONG
#  define PyInt_AsLong PyLong_AsLong
#  define PyInt_AsUnsignedLongMask PyLong_AsUnsignedLongMask
#  define PyNumber_Int PyNumber_Long
#endif

/* Python 3.2 changed the type of hash values, so paper over this annoying
 * difference.
 */
#if PY_VERSION_HEX < 0x03020000
  typedef long Py_hash_t;
#endif

/* Python 3 always has the `CHECKTYPES' behaviour, and doesn't define the
 * flag.
 */
#ifdef PY3
#  define Py_TPFLAGS_CHECKTYPES 0
#endif

/* Plain octet strings.  Python 2 calls these `str', while Python 3 calls
 * them `bytes'.  We call them `bin' here, and define the following.
 *
 *   * `BINOBJ' is the C type of a `bin' object.
 *   * `BIN_TYPE' is the Python `type' object for `bin'.
 *   * `BIN_CHECK(OBJ)' is true if OBJ is a `bin' object.
 *   * `BIN_PTR(OBJ)' points to the first octet of OBJ, without checking!
 *   * `BIN_LEN(OBJ)' yields the length of OBJ in octets, without checking!
 *   * `BIN_FROMSTR(STR)' makes a `bin' object from a null-terminated string.
 *   * `BIN_FORMAT(FMT, ARGS...)' and `BIN_VFORMAT(FMT, AP)' make a `bin'
 *     object from a `printf'-like format string and arguments.
 *   * `BIN_PREPAREWRITE(OBJ, PTR, LEN)' prepares to make a `bin' object: it
 *     sets PTR to point to a buffer of LEN bytes; call `BIN_DONEWRITE' when
 *     finished.  The variable OBJ will eventually be the resulting object,
 *     but until `BIN_DONEWRITE' is called, it may in fact be some different
 *     object.
 *   * `BIN_DONEWRITE(OBJ, LEN)' completes making a `bin' object: it adjusts
 *     its length to be LEN, which must not be larger than the LEN given to
 *     `BIN_PREPAREWRITE', and sets OBJ to point to the finished object.
 *   * `BIN_SETLEN(OBJ, LEN)' adjusts the length of OBJ downwards to LEN,
 *     without checking!
 #   * `Y' is a format character for `PyArg_ParseTuple...' for retrieving a
 *     null-terminated octet string from a `bin' object.
 #   * `YN' is a format character for `PyArg_ParseTuple...' for retrieving an
 *     octet string and length from any sort-of vaguely binary-ish object.
 */
#ifdef PY3
#  define BINOBJ PyBytesObject
#  define BIN_TYPE PyBytes_Type
#  define BIN_CHECK(obj) PyBytes_Check(obj)
#  define BIN_PTR(obj) PyBytes_AS_STRING(obj)
#  define BIN_LEN(obj) PyBytes_GET_SIZE(obj)
#  define BIN_FROMSTR(str) PyBytes_FromString(str)
#  define BIN_FROMSTRLEN(str, len) PyBytes_FromStringAndSize(str, len)
#  define BIN_FORMAT PyBytes_FromFormat
#  define BIN_VFORMAT PyBytes_FromFormatV
#  define BIN_PREPAREWRITE(obj, ptr, sz) do {				\
     (obj) = PyBytes_FromStringAndSize(0, (sz));			\
     (ptr) = PyBytes_AS_STRING(obj);					\
   } while (0)
#  define BIN_DONEWRITE(obj, sz) do Py_SIZE(obj) = (sz); while (0)
#  define BIN_SETLEN(obj, len) do Py_SIZE(obj) = (len); while (0)
#  define Y "y"
#  define YN "y#"
#else
#  define BINOBJ PyStringObject
#  define BIN_TYPE PyString_Type
#  define BIN_CHECK(obj) PyString_Check(obj)
#  define BIN_PTR(obj) PyString_AS_STRING(obj)
#  define BIN_LEN(obj) PyString_GET_SIZE(obj)
#  define BIN_FROMSTR(str) PyString_FromString(str)
#  define BIN_FROMSTRLEN(str, len) PyString_FromStringAndSize(str, len)
#  define BIN_FORMAT PyString_FromFormat
#  define BIN_VFORMAT PyString_FromFormatV
#  define BIN_PREPAREWRITE(obj, ptr, sz) do {				\
     (obj) = PyString_FromStringAndSize(0, (sz));			\
     (ptr) = PyString_AS_STRING(obj);					\
   } while (0)
#  define BIN_DONEWRITE(obj, sz) do Py_SIZE(obj) = (sz); while (0)
#  define BIN_SETLEN(obj, len) do Py_SIZE(obj) = (len); while (0)
#  define Y "s"
#  define YN "s#"
#endif

/* Text strings.  Both Python 2 and Python 3 call these `str', but they're
 * very different because a Python 3 `str' is Unicode inside.  When dealing
 * with Python 3 text, the data is UTF-8 encoded.  We call them `text' here,
 * and define the following.
 *
 *   * `TEXTOBJ' is the C type of a `text' object.
 *   * `TEXT_TYPE' is the Python `type' object for `text'.
 *   * `TEXT_CHECK(OBJ)' is true if OBJ is a `text' object.
 *   * `TEXT_STR(OBJ)' points to the first byte of a null-terminated string
 *     OBJ, or is null.
 *   * `TEXT_PTR(OBJ)' points to the first byte of OBJ, without checking!
 *   * `TEXT_LEN(OBJ)' yields the length of OBJ in octets, without checking!
 *   * `TEXT_FROMSTR(STR)' makes a `text' object from a null-terminated
 *     string.
 *   * `TEXT_FORMAT(FMT, ARGS...)' and `TEST_VFORMAT(FMT, AP)' make a `text'
 *     object from a `printf'-like format string and arguments.
 *   * `TEXT_PREPAREWRITE(OBJ, PTR, LEN)' prepares to make a `text' object:
 *     it sets PTR to point to a buffer of LEN bytes; call `TEXT_DONEWRITE'
 *     when finished.  The variable OBJ will eventually be the resulting
 *     object, but until `TEXT_DONEWRITE' is called, it may in fact be some
 *     different object.
 *   * `TEXT_DONEWRITE(OBJ, LEN)' completes making a `text' object: it
 *     adjusts its length to be LEN, which must not be larger than the LEN
 *     given to `TEXT_PREPAREWRITE', and sets OBJ to point to the finished
 *     object.
 *
 * (Use `s' and `s#' in `PyArg_ParseTuple...'.)
 */
#ifdef PY3
#  define TEXTOBJ PyUnicodeObject
#  define TEXT_TYPE PyUnicode_Type
#  define TEXT_CHECK(obj) PyUnicode_Check(obj)
#  if PY_VERSION_HEX >= 0x03030000
#    define TEXT_PTR(obj) PyUnicode_AsUTF8(obj)
#    define TEXT_STR(obj) PyUnicode_AsUTF8(obj)
#    define TEXT_PTRLEN(obj, ptr, len) do {				\
       Py_ssize_t len_;							\
       (ptr) = PyUnicode_AsUTF8AndSize((obj), &len_);			\
       (len) = len_;							\
     } while (0)
#    define TEXT_PREPAREWRITE(obj, ptr, sz) do {			\
       (obj) = PyUnicode_New((sz), 127);				\
       (ptr) = PyUnicode_DATA(obj);					\
     } while (0)
#    define TEXT_DONEWRITE(obj, len) do {				\
       size_t len_ = (len);						\
       assert(PyUnicode_IS_COMPACT_ASCII(obj));				\
       ((char *)PyUnicode_DATA(obj))[len_] = 0;				\
       ((PyASCIIObject *)(obj))->length = len_;				\
     } while (0)
#  else
#    define TEXT_PTR(obj) _PyUnicode_AsString(obj)
#    define TEXT_STR(obj) _PyUnicode_AsString(obj)
#    define TEXT_PTRLEN(obj, ptr, len) do {				\
       Py_ssize_t len_;							\
       (ptr) = _PyUnicode_AsStringAndSize((obj), &len_);		\
       (len) = len_;							\
     } while (0)
#    define TEXT_PREPAREWRITE(obj, ptr, sz) do {			\
       (obj) = PyBytes_FromStringAndSize(0, (sz));			\
       (ptr) = PyBytes_AS_STRING(obj);					\
     } while (0)
#    define TEXT_DONEWRITE(obj, len) do {				\
       PyObject *new_;							\
       Py_SIZE(obj) = (len);						\
       new_ = PyUnicode_FromEncodedObject(obj, 0, 0);			\
       assert(new_); Py_DECREF(obj); (obj) = new_;			\
     } while (0)
#  endif
#  define TEXT_FORMAT PyUnicode_FromFormat
#  define TEXT_VFORMAT PyUnicode_FromFormatV
#  define TEXT_FROMSTR(str) PyUnicode_FromString(str)
#  define TEXT_FROMSTRLEN(str, len) PyUnicode_FromStringAndSize(str, len)
#else
#  define TEXTOBJ PyStringObject
#  define TEXT_TYPE PyString_Type
#  define TEXT_CHECK(obj) PyString_Check(obj)
#  define TEXT_PTR(obj) PyString_AS_STRING(obj)
#  define TEXT_STR(obj) PyString_AsString(obj)
#  define TEXT_PTRLEN(obj, ptr, len) do {				\
     (ptr) = PyString_AS_STRING(obj);					\
     (len) = PyString_GET_SIZE(obj);					\
   } while (0)
#  define TEXT_FORMAT PyString_FromFormat
#  define TEXT_VFORMAT PyString_FromFormatV
#  define TEXT_PREPAREWRITE(obj, ptr, sz) do {				\
     (obj) = PyString_FromStringAndSize(0, (sz));			\
     (ptr) = PyString_AS_STRING(obj);					\
   } while (0)
#  define TEXT_DONEWRITE(obj, sz) do { Py_SIZE(obj) = (sz); } while (0)
#  define TEXT_FROMSTR(str) PyString_FromString(str)
#  define TEXT_FROMSTRLEN(str, len) PyString_FromStringAndSize(str, len)
#endif

/*----- Utilities for returning values and exceptions ---------------------*/

/* Returning values. */
#define RETURN_OBJ(obj) do { Py_INCREF(obj); return (obj); } while (0)
#define RETURN_NONE RETURN_OBJ(Py_None)
#define RETURN_NOTIMPL RETURN_OBJ(Py_NotImplemented)
#define RETURN_TRUE RETURN_OBJ(Py_True)
#define RETURN_FALSE RETURN_OBJ(Py_False)
#define RETURN_ME RETURN_OBJ(me)

/* Returning exceptions.  (Note that `KeyError' is `MAPERR' here, because
 * Catacomb has its own kind of `KeyError'.)
 */
#define EXCERR(exc, str) do {						\
  PyErr_SetString(exc, str);						\
  goto end;								\
} while (0)
#define VALERR(str) EXCERR(PyExc_ValueError, str)
#define OVFERR(str) EXCERR(PyExc_OverflowError, str)
#define TYERR(str) EXCERR(PyExc_TypeError, str)
#define IXERR(str) EXCERR(PyExc_IndexError, str)
#define ZDIVERR(str) EXCERR(PyExc_ZeroDivisionError, str)
#define SYSERR(str) EXCERR(PyExc_SystemError, str)
#define NIERR(str) EXCERR(PyExc_NotImplementedError, str)
#define MAPERR(idx) do {						\
  PyErr_SetObject(PyExc_KeyError, idx);					\
  goto end;								\
} while (0)
#define OSERR(name) do {						\
  PyErr_SetFromErrnoWithFilename(PyExc_OSError, name);			\
  goto end;								\
} while (0)

/* Saving and restoring exceptions. */
struct excinfo { PyObject *ty, *val, *tb; };
#define EXCINFO_INIT { 0, 0, 0 }
#define INIT_EXCINFO(exc) do {						\
  struct excinfo *_exc = (exc); _exc->ty = _exc->val = _exc->tb = 0;	\
} while (0)
#define RELEASE_EXCINFO(exc) do {					\
  struct excinfo *_exc = (exc);						\
  Py_XDECREF(_exc->ty);	 _exc->ty  = 0;					\
  Py_XDECREF(_exc->val); _exc->val = 0;					\
  Py_XDECREF(_exc->tb);	 _exc->tb  = 0;					\
} while (0)
#define STASH_EXCINFO(exc) do {						\
  struct excinfo *_exc = (exc);						\
  PyErr_Fetch(&_exc->ty, &_exc->val, &_exc->tb);			\
  PyErr_NormalizeException(&_exc->ty, &_exc->val, &_exc->tb);		\
} while (0)
#define RESTORE_EXCINFO(exc) do {					\
  struct excinfo *_exc = (exc);						\
  PyErr_Restore(_exc->ty, _exc->val, _exc->tb);				\
  _exc->ty = _exc->val = _exc->tb = 0;					\
} while (0)
extern void report_lost_exception(struct excinfo *, const char *, ...);
extern void report_lost_exception_v(struct excinfo *, const char *, va_list);
extern void stash_exception(struct excinfo *, const char *, ...);
extern void restore_exception(struct excinfo *, const char *, ...);

/*----- Conversions -------------------------------------------------------*/

/* Define an input conversion (`O&') function: check that the object has
 * Python type TY, and extract a C pointer to CTY by calling EXT on the
 * object (which may well be a macro).
 */
#define CONVFUNC(ty, cty, ext)						\
  int conv##ty(PyObject *o, void *p)					\
  {									\
    if (!PyObject_TypeCheck(o, ty##_pytype))				\
      TYERR("wanted a " #ty);						\
    *(cty *)p = ext(o);							\
    return (1);								\
  end:									\
    return (0);								\
  }

/* Input conversion functions for standard kinds of objects, with overflow
 * checking where applicable.
 */
struct bin { Py_buffer vw; const void *p; Py_ssize_t sz; };
#define BIN_INIT { { 0 } 0, 0 }

extern int convulong(PyObject *, void *); /* unsigned long */
extern int convuint(PyObject *, void *); /* unsigned int */
extern int convszt(PyObject *, void *);	/* size_t */
extern int convbool(PyObject *, void *); /* bool */
extern int convbin(PyObject *, void *); /* read buffer holding bytes */
extern void freebin(struct bin *);

/* Output conversions. */
extern PyObject *getbool(int);		/* bool */
extern PyObject *getulong(unsigned long); /* any kind of unsigned integer */

/*----- Miscellaneous utilities -------------------------------------------*/

#define FREEOBJ(obj) (Py_TYPE(obj)->tp_free((PyObject *)(obj)))
  /* Actually free OBJ, e.g., in a deallocation function. */

extern PyObject *abstract_pynew(PyTypeObject *, PyObject *, PyObject *);
  /* A `tp_new' function which refuses to make the object. */

extern PyObject *enrich_compare(int /*op*/, int /*cmp*/);
  /* Use a traditional compare-against-zero comparison result CMP to answer a
   * modern Python `tp_richcompare' operation OP.
   */

#ifndef CONVERT_CAREFULLY
#  define CONVERT_CAREFULLY(newty, expty, obj)				\
     (!sizeof(*(expty *)0 = (obj)) + (/*unconst*/ newty)(obj))
  /* Convert OBJ to the type NEWTY, having previously checked that it is
   * convertible to the expected type EXPTY.
   *
   * Because of the way we set up types, we can make many kinds of tables be
   * `const' which can't usually be so (because Python will want to fiddle
   * with their reference counts); and, besides, Python's internals are
   * generally quite bad at being `const'-correct about tables.  One frequent
   * application of this macro, then, is in removing `const' from a type
   * without sacrificing all type safety.  The other common use is in
   * checking that method function types match up with the signatures
   * expected in their method definitions.
   */
#endif

#define KWLIST CONVERT_CAREFULLY(char **, const char *const *, kwlist)
  /* Strip `const' qualifiers from the keyword list `kwlist'.  Useful when
   * calling `PyArg_ParseTupleAndKeywords', which isn't `const'-correct.
   */

/*----- Type definitions --------------------------------------------------*
 *
 * Pyke types are defined in a rather unusual way.
 *
 * The main code defines a `type skeleton' of type `PyTypeObject',
 * conventionally named `TY_pytype_skel'.  Unlike typical Python type
 * definitions in extensions, this can (and should) be read-only.  Also,
 * there's no point in setting the `tp_base' pointer here, because the actual
 * runtime base type object won't, in general, be known at compile time.
 * Instead, the type skeletons are converted into Python `heap types' by the
 * `INITTYPE' macro.  The main difference is that Python code can add
 * attributes to heap types, and we make extensive use of this ability.
 */

extern void *newtype(PyTypeObject */*meta*/,
		     const PyTypeObject */*skel*/, const char */*name*/);
  /* Make and return a new Python type object, of type META (typically
   * `PyType_Type', but may be a subclass), filled in from the skeleton SKEL
   * (null to inherit everything), and named NAME.  The caller can mess with
   * the type object further at this time: call `typeready' when it's set up
   * properly.
   */

extern void typeready(PyTypeObject *);
  /* The type object is now ready to be used. */

extern PyTypeObject *inittype(const PyTypeObject */*skel*/,
			      PyTypeObject */*base*/,
			      PyTypeObject */*meta*/);
  /* All-in-one function to construct a working type from a type skeleton
   * SKEL, with known base type BASE (null for `object') and metaclass.
   */

/* Alias for built-in types, to fit in with Pyke naming conventions. */
#define root_pytype 0
#define type_pytype &PyType_Type

#define INITTYPE_META(ty, base, meta) do {				\
  ty##_pytype = inittype(&ty##_pytype_skel, base##_pytype, meta##_pytype); \
} while (0)
#define INITTYPE(ty, base) INITTYPE_META(ty, base, type)
  /* Macros to initialize a type from its skeleton. */

/* Macros for filling in `PyMethodDef' tables, ensuring that functions have
 * the expected signatures.
 */
#define STD_METHOD(decor, func, flags, doc)				\
  { #func, decor(func), METH_VARARGS | flags, doc },
#define KEYWORD_METHOD(decor, func, flags, doc)				\
  { #func,								\
    CONVERT_CAREFULLY(PyCFunction, PyCFunctionWithKeywords, decor(func)), \
    METH_VARARGS | METH_KEYWORDS | flags,				\
    doc },
#define NOARG_METHOD(decor, func, flags, doc)				\
  { #func,								\
    CONVERT_CAREFULLY(PyCFunction, PyNoArgsFunction, decor(func)),	\
    METH_NOARGS | flags,						\
    doc },

/* Convenience wrappers for filling in `PyMethodDef' tables, following
 * Pyke naming convention.  Define `METHNAME' locally as
 *
 *	#define METHNAME(name) foometh_##func
 *
 * around the method table.
 */
#define METH(func, doc) STD_METHOD(METHNAME, func, 0, doc)
#define KWMETH(func, doc) KEYWORD_METHOD(METHNAME, func, 0, doc)
#define NAMETH(func, doc) NOARG_METHOD(METHNAME, func, 0, doc)
#define CMTH(func, doc) STD_METHOD(METHNAME, func, METH_CLASS, doc)
#define KWCMTH(func, doc) KEYWORD_METHOD(METHNAME, func, METH_CLASS, doc)
#define NACMTH(func, doc) NOARG_METHOD(METHNAME, func, METH_CLASS, doc)
#define SMTH(func, doc) STD_METHOD(METHNAME, func, METH_STATIC, doc)
#define KWSMTH(func, doc) KEYWORD_METHOD(METHNAME, func, METH_STATIC, doc)
#define NASMTH(func, doc) NOARG_METHOD(METHNAME, func, METH_STATIC, doc)

/* Convenience wrappers for filling in `PyGetSetDef' tables, following Pyke
 * naming convention.  Define `GETSETNAME' locally as
 *
 *	#define GETSETNAME(op, name) foo##op##_##func
 *
 * around the get/set table.
 */
#define GET(func, doc)							\
  { #func, GETSETNAME(get, func), 0, doc },
#define GETSET(func, doc)						\
  { #func, GETSETNAME(get, func), GETSETNAME(set, func), doc },

/* Convenience wrappers for filling in `PyMemberDef' tables.  Define
 * `MEMBERSTRUCT' locally as
 *
 *	#define MEMBERSTRUCT foo_pyobj
 *
 * around the member table.
 */
#define MEMRNM(name, ty, mem, f, doc)					\
  { #name, ty, offsetof(MEMBERSTRUCT, mem), f, doc },
#define MEMBER(name, ty, f, doc) MEMRNM(name, ty, name, f, doc)

/* Wrappers for filling in pointers in a `PyTypeObject' structure, (a)
 * following Pyke naming convention, and (b) stripping `const' from the types
 * without losing type safety.
 */
#define UNCONST_TYPE_SLOT(type, suffix, op, ty)				\
  CONVERT_CAREFULLY(type *, const type *, op ty##_py##suffix)
#define PYGETSET(ty) UNCONST_TYPE_SLOT(PyGetSetDef, getset, NOTHING, ty)
#define PYMETHODS(ty) UNCONST_TYPE_SLOT(PyMethodDef, methods, NOTHING, ty)
#define PYMEMBERS(ty) UNCONST_TYPE_SLOT(PyMemberDef, members, NOTHING, ty)
#define PYNUMBER(ty) UNCONST_TYPE_SLOT(PyNumberMethods, number, &, ty)
#define PYSEQUENCE(ty) UNCONST_TYPE_SLOT(PySequenceMethods, sequence, &, ty)
#define PYMAPPING(ty) UNCONST_TYPE_SLOT(PyMappingMethods, mapping, &, ty)
#define PYBUFFER(ty) UNCONST_TYPE_SLOT(PyBufferProcs, buffer, &, ty)

/*----- Populating modules ------------------------------------------------*/

extern PyObject *modname;
  /* The overall module name.  Set this with `TEXT_FROMSTR'. */

extern PyObject *home_module;
  /* The overall module object. */

extern PyObject *mkexc(PyObject */*mod*/, PyObject */*base*/,
		       const char */*name*/, const PyMethodDef */*methods*/);
  /* Make and return an exception class called NAME, which will end up in
   * module MOD (though it is not added at this time).  The new class is a
   * subclass of BASE.  Attach the METHODS to it.
   */

#define INSERT(name, ob) do {						\
  PyObject *_o = (PyObject *)(ob);					\
  Py_INCREF(_o);							\
  PyModule_AddObject(mod, name, _o);					\
} while (0)
  /* Insert a Python object OB into the module `mod' under the given NAME. */

/* Numeric constants. */
struct nameval { const char *name; unsigned f; unsigned long value; };
#define CF_SIGNED 1u
extern void setconstants(PyObject *, const struct nameval *);
#define CONST(x) { #x, (x) >= 0 ? 0 : CF_SIGNED, x }
#define CONSTFLAG(f, x) { #x, f, x }

#define INSEXC(name, var, base, meth)					\
  INSERT(name, var = mkexc(mod, base, name, meth))
  /* Insert an exception class into the module `mod'; other arguments are as
   * for `mkexc'.
   */

/*----- Submodules --------------------------------------------------------*
 *
 * It's useful to split the Python module up into multiple source files, and
 * have each one contribute its definitions into the main module.
 *
 * Define a list-macro `MODULES' in the master header file naming the
 * submodules to be processed, and run
 *
 *	MODULES(DECLARE_MODINIT)
 *
 * to declare the interface functions.
 *
 * Each submodule FOO defines two functions: `FOO_pyinit' initializes types
 * (see `INITTYPE' above) and accumulates methods (`addmethods' below), while
 * `FOO_pyinsert' populates the module with additional definitions
 * (especially types, though also constants).
 *
 * The top-level module initialization should call `INIT_MODULES' before
 * creating the Python module, and `INSERT_MODULES' afterwards to make
 * everything work.
 */

extern void addmethods(const PyMethodDef *);
extern PyMethodDef *donemethods(void);
  /* Accumulate method-table fragments, and return the combined table of all
   * of the fragments.
   */

#define DECLARE_MODINIT(m)						\
  extern void m##_pyinit(void);						\
  extern void m##_pyinsert(PyObject *);
  /* Declare submodule interface functions. */

#define DOMODINIT(m) m##_pyinit();
#define DOMODINSERT(m) m##_pyinsert(mod);
#define INIT_MODULES do { MODULES(DOMODINIT) } while (0)
#define INSERT_MODULES do { MODULES(DOMODINSERT) } while (0)
  /* Top-level dispatch to the various submodules. */

/*----- Generic mapping support -------------------------------------------*/

/* Operations table.  ME is the mapping object throughout. */
typedef struct gmap_ops {
  size_t isz;				/* iterator size */

  void *(*lookup)(PyObject *me, PyObject *key, unsigned *f);
    /* Lookup the KEY.  If it is found, return an entry pointer for it; if F
     * is not null, set *F nonzero.  Otherwise, if F is null, return a null
     * pointer (without setting a pending exception); if F is not null, then
     * set *F zero and return a fresh entry pointer.  Return null on a Python
     * exception (the caller will notice the difference.)
     */

  void (*iter_init)(PyObject *me, void *i);
    /* Initialize an iterator at I. */

  void *(*iter_next)(PyObject *me, void *i);
    /* Return an entry pointer for a different item, or null if all have been
     * visited.
     */

  PyObject *(*entry_key)(PyObject *me, void *e);
    /* Return the key object for a mapping entry. */

  PyObject *(*entry_value)(PyObject *me, void *e);
    /* Return the value object for a mapping entry. */

  int (*set_entry)(PyObject *me, void *e, PyObject *val);
    /* Modify the entry by storing VAL in its place.  Return 0 on success,
     * or -1 on a Python error.
     */

  int (*del_entry)(PyObject *me, void *e);
    /* Delete the entry.  (It may be necessary to delete a freshly allocated
     * entry, e.g., if `set_entry' failed.)  Return 0 on success, or -1 on a
     * Python error.
     */
} gmap_ops;

/* The intrusion at the head of a mapping object. */
#define GMAP_PYOBJ_HEAD							\
  PyObject_HEAD								\
  const gmap_ops *gmops;

typedef struct gmap_pyobj {
  GMAP_PYOBJ_HEAD
} gmap_pyobj;
#define GMAP_OPS(obj) (((gmap_pyobj *)(obj))->gmops)
  /* Discover the operations from a mapping object. */

/* Mapping methods. */
#define GMAP_METMNAME(func) gmapmeth_##func
#define GMAP_METH(func, doc) STD_METHOD(GMAP_METMNAME, func, 0, doc)
#define GMAP_KWMETH(func, doc) KEYWORD_METHOD(GMAP_METMNAME, func, 0, doc)
#define GMAP_NAMETH(func, doc) NOARG_METHOD(GMAP_METMNAME, func, 0, doc)
#define GMAP_METHDECL(func, doc)					\
  extern PyObject *gmapmeth_##func(PyObject *, PyObject *);
#define GMAP_KWMETHDECL(func, doc)					\
  extern PyObject *gmapmeth_##func(PyObject *, PyObject *, PyObject *);
#define GMAP_NAMETHDECL(func, doc)					\
  extern PyObject *gmapmeth_##func(PyObject *);

#ifdef PY3
#  define GMAP_DOROMETHODS(METH, KWMETH, NAMETH)			\
    NAMETH(keys,	"D.keys() -> LIST")				\
    NAMETH(values,	"D.values() -> LIST")				\
    NAMETH(items,	"D.items() -> LIST")				\
    KWMETH(get,		"D.get(KEY, [default = None]) -> VALUE")
#else
#  define GMAP_DOROMETHODS(METH, KWMETH, NAMETH)			\
    METH  (has_key,	"D.has_key(KEY) -> BOOL")			\
    NAMETH(keys,	"D.keys() -> LIST")				\
    NAMETH(values,	"D.values() -> LIST")				\
    NAMETH(items,	"D.items() -> LIST")				\
    NAMETH(iterkeys,	"D.iterkeys() -> ITER")				\
    NAMETH(itervalues,	"D.itervalues() -> ITER")			\
    NAMETH(iteritems,	"D.iteritems() -> ITER")			\
    KWMETH(get,		"D.get(KEY, [default = None]) -> VALUE")
#endif

#define GMAP_DOMETHODS(METH, KWMETH, NAMETH)				\
  GMAP_DOROMETHODS(METH, KWMETH, NAMETH)				\
  NAMETH(clear,		"D.clear()")					\
  KWMETH(setdefault,	"D.setdefault(K, [default = None]) -> VALUE")	\
  KWMETH(pop,		"D.pop(KEY, [default = <error>]) -> VALUE")	\
  NAMETH(popitem,	"D.popitem() -> (KEY, VALUE)")			\
  KWMETH(update,	"D.update(MAP)")

GMAP_DOMETHODS(GMAP_METHDECL, GMAP_KWMETHDECL, GMAP_NAMETHDECL)
#define GMAP_ROMETHODS GMAP_DOROMETHODS(GMAP_METH, GMAP_KWMETH, GMAP_NAMETH)
#define GMAP_METHODS GMAP_DOMETHODS(GMAP_METH, GMAP_KWMETH, GMAP_NAMETH)

/* Mapping protocol implementation. */
extern Py_ssize_t gmap_pysize(PyObject *); /* for `mp_length' */
extern PyObject *gmap_pyiter(PyObject *); /* for `tp_iter' */
extern PyObject *gmap_pylookup(PyObject *, PyObject *); /* for `mp_subscript' */
extern int gmap_pystore(PyObject *, PyObject *, PyObject *); /* for `mp_ass_subscript' */
extern int gmap_pyhaskey(PyObject *, PyObject *); /* for `sq_contains' */
extern const PySequenceMethods gmap_pysequence; /* for `tp_as_sequence' */
extern const PyMethodDef gmapro_pymethods[]; /* read-only methods */
extern const PyMethodDef gmap_pymethods[]; /* all the standard methods */

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif