2.1. Atom Protocol#

Caterpillar provides a special protocol for working with atoms. It is designed to incorporate packing and unpacking of data streams as well as calculating its size and measuring its type.

type CpAtomObject#: All classes that implement capabilities of an atom should inherit from this class. It defines, but does not implement all four protocol methods. There are no specific members - consider this class to be an abstract base class.

PyTypeObject CpAtom_Type#: The type object of the CpAtom class.

The following functions are subject to change in the next release.

PyObject *CpAtom_CallPack(PyObject *self, PyObject *name, PyObject *o, PyObject *ctx)#

Packs the object o using context ctx and returns the result. The name describes the target method name to be called on the object self. This method will return NULL if an error occurs while calling the target method. Proper use would be together with the global module state:

_coremodulestate* state = /*...*/;
PyObject *o = ..., *ctx = ...;

// invoke __pack__ manually
PyObject* result = CpAtom_CallPack(self, state->str___pack__, o, ctx);
if (!result) {
    return NULL;
}
// do something with result

The provided context object must support the Context Protocol, which is not validated in this method. Furthermore, it must be an instance of the CpState structure if the native pack function is called. This function may return NotImplemented to indicate that this class does not support packing.

PyObject *CpAtom_CallSize(PyObject *self, PyObject *name, PyObject *ctx)#: Calculates the size of the object self using context ctx and returns the result. The name describes the target method name to be called on the object self. This method will return NULL if an error occurs while calling the target function.

int CpAtom_CanPack(PyObject *o)#
int CpAtom_FastCanPack(PyObject *o, _coremodulestate *state)#: Return 1 if the object provides an interface of packing other objects and 0 otherwise. Note that it returns 1 for classes with a __pack__() method, since the type of objects to be packed can not be determined by introspection.

int CpAtom_CanUnpack(PyObject *o)#
int CpAtom_FastCanUnpack(PyObject *o, _coremodulestate *state)#: Return 1 if the object provides an interface of unpacking other objects and 0 otherwise. Note that it returns 1 for classes with a __unpack__() method, since the type of objects to be unpacked can not be determined by introspection.

int CpAtom_HasType(PyObject *o)#
int CpAtom_FastHasType(PyObject *o, _coremodulestate *state)#: Returns 1 if the object provides a method of determining the type this object (usually an atom) represents and 0 otherwise. As all other functions, this one will simply check for the presence of the __type__() method.

int CpAtom_HasSize(PyObject *o)#
int CpAtom_FastHasSize(PyObject *o, _coremodulestate *state)#: Searches for __size__(), returns 1 if it is present and 0 otherwise.

Note

For each function introduced above, there is an alternative (faster) implementation that won’t create a Python unicode object before calling getattr. So, if a reference _codemodulestate is owned, it’s string cache will be used.