[Zodb-checkins] CVS: Zope/lib/python/BTrees - Maintainer.txt:1.1

[Jim Fulton]

Update of /cvs-repository/Zope/lib/python/BTrees
In directory cvs.zope.org:/tmp/cvs-serv3534

Added Files:
	Maintainer.txt 
Log Message:
*** empty log message ***

=== Added File Zope/lib/python/BTrees/Maintainer.txt ===
This document provides information for developers who maintain or
extend BTrees.

BTrees are defined using a "template", roughly akin to a a C++
template. To create a new family of BTrees, create a source file that
defined macros used to handle differences in key and value types:

  MASTER_ID provides a string to hold an RCS/CVS Id key to be included
  in compiled binaries.

  MOD_NAME_PREFIX provides the prefix used for the module. This gets
  used to generate type names and the internal module name string.

  DEFAULT_MAX_BUCKET_SIZE The maximum bucket size. Someday this will
  be tunable on BTree instances.

  DEFAULT_MAX_BTREE_SIZE The maximum btree size (number of
  children). Someday this will be tunable on BTree instances.

  KEY_TYPE The C type declaration for the key data (e.g. "int",
  "PyObject *").

  KEY_CHECK(K) Macro that tests whether a Python Object, K, can be
  converted to the (C) key type (KEY_TYPE). This macro should return a
  bollean. An exception will generally be raised if this returns false.

  TEST_KEY(K, T) Compares (ala Python cmp) K & T, where K & T are C
  data values (of type KEY_TYPE). Returns -1 for K < T, 0 for K == T,
  or -1 if K > T.

  DECREF_KEY(K) DECREFs the key of KEY_TYPE is PyObject* or is a no
  op.

  INCREF_KEY(K)  DECREFs the key of KEY_TYPE is PyObject* or is a no
  op.
  
  COPY_KEY(K, E) Copy a key's value from E to K.  Note that this
  doesn't INCREF when KEY_TYPE is PyObject*.

  COPY_KEY_TO_OBJECT(O, K) Sets the PyObject* O to a PyObject*
  representation of K. Note that this is a new reference, so we INCREF
  when KEY_TYPE is PyObject*.

  COPY_KEY_FROM_ARG(TARGET, ARG, STATUS) Copy an rgument to the target
  without creating a new reference to ARG. If this can't be done, set
  a Python error and set status to 0. If there is no error, status is
  unchanged. 



  VALUE_TYPE The C type declaration for the value data (e.g. "int",
  "PyObject *").

  TEST_VALUE(K, T) Compares (ala Python cmp) K & T, where K & T are C
  data values (of type VALUE_TYPE). Returns -1 for K < T, 0 for K == T,
  or -1 if K > T.

  DECREF_VALUE(K) DECREFs the value of VALUE_TYPE is PyObject* or is a no
  op.

  INCREF_VALUE(K)  DECREFs the value of VALUE_TYPE is PyObject* or is a no
  op.
  
  COPY_VALUE(K, E) Copy a value's value from E to K.  Note that this
  doesn't INCREF when VALUE_TYPE is PyObject*.

  COPY_VALUE_TO_OBJECT(O, K) Sets the PyObject* O to a PyObject*
  representation of K. Note that this is a new reference, so we INCREF
  when VALUE_TYPE is PyObject*.

  COPY_VALUE_FROM_ARG(TARGET, ARG, STATUS) Copy an rgument to the target
  without creating a new reference to ARG. If this can't be done, set
  a Python error and set status to 0. If there is no error, status is
  unchanged. 

  NORMALIZE_VALUE(V, MIN) Normalize the value, V, using the parameter
  MIN. This almost vertainly a YAGNI. It is a no op for most
  types. For integers, V is replaced by V/MIN only if MIN > 0.

  MERGE_DEFAULT is a macro that should be set to the default value for
  sets when sets are are merged with mappings via weighed union or
  intersection.  
  
  MERGE(O1, w1, O2, w2) This macro performs a weighted merge of two
  values, O1 and O2 using weights w1 and w2. Note that weighted unions
  and intersections are not enabled if this macro is undefined.

  MERGE_WEIGHT(O, w) Computes a weighted value for O. This is used for
  "filling out" weighted unions.