Guido van Rossum | f70e43a | 1991-02-19 12:39:46 +0000 | [diff] [blame] | 1 | /*********************************************************** |
Guido van Rossum | 5113f5f | 1992-04-05 14:20:22 +0000 | [diff] [blame] | 2 | Copyright 1991, 1992 by Stichting Mathematisch Centrum, Amsterdam, The |
Guido van Rossum | f70e43a | 1991-02-19 12:39:46 +0000 | [diff] [blame] | 3 | Netherlands. |
| 4 | |
| 5 | All Rights Reserved |
| 6 | |
| 7 | Permission to use, copy, modify, and distribute this software and its |
| 8 | documentation for any purpose and without fee is hereby granted, |
| 9 | provided that the above copyright notice appear in all copies and that |
| 10 | both that copyright notice and this permission notice appear in |
| 11 | supporting documentation, and that the names of Stichting Mathematisch |
| 12 | Centrum or CWI not be used in advertising or publicity pertaining to |
| 13 | distribution of the software without specific, written prior permission. |
| 14 | |
| 15 | STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO |
| 16 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND |
| 17 | FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE |
| 18 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| 19 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
| 20 | ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT |
| 21 | OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| 22 | |
| 23 | ******************************************************************/ |
| 24 | |
Guido van Rossum | 3f5da24 | 1990-12-20 15:06:42 +0000 | [diff] [blame] | 25 | #define NDEBUG |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 26 | /* Object and type object interface */ |
| 27 | |
| 28 | /* |
| 29 | 123456789-123456789-123456789-123456789-123456789-123456789-123456789-12 |
| 30 | |
| 31 | Objects are structures allocated on the heap. Special rules apply to |
| 32 | the use of objects to ensure they are properly garbage-collected. |
| 33 | Objects are never allocated statically or on the stack; they must be |
| 34 | accessed through special macros and functions only. (Type objects are |
| 35 | exceptions to the first rule; the standard types are represented by |
| 36 | statically initialized type objects.) |
| 37 | |
| 38 | An object has a 'reference count' that is increased or decreased when a |
| 39 | pointer to the object is copied or deleted; when the reference count |
| 40 | reaches zero there are no references to the object left and it can be |
| 41 | removed from the heap. |
| 42 | |
| 43 | An object has a 'type' that determines what it represents and what kind |
| 44 | of data it contains. An object's type is fixed when it is created. |
| 45 | Types themselves are represented as objects; an object contains a |
| 46 | pointer to the corresponding type object. The type itself has a type |
| 47 | pointer pointing to the object representing the type 'type', which |
| 48 | contains a pointer to itself!). |
| 49 | |
| 50 | Objects do not float around in memory; once allocated an object keeps |
| 51 | the same size and address. Objects that must hold variable-size data |
| 52 | can contain pointers to variable-size parts of the object. Not all |
| 53 | objects of the same type have the same size; but the size cannot change |
| 54 | after allocation. (These restrictions are made so a reference to an |
| 55 | object can be simply a pointer -- moving an object would require |
| 56 | updating all the pointers, and changing an object's size would require |
| 57 | moving it if there was another object right next to it.) |
| 58 | |
| 59 | Objects are always accessed through pointers of the type 'object *'. |
| 60 | The type 'object' is a structure that only contains the reference count |
| 61 | and the type pointer. The actual memory allocated for an object |
| 62 | contains other data that can only be accessed after casting the pointer |
| 63 | to a pointer to a longer structure type. This longer type must start |
| 64 | with the reference count and type fields; the macro OB_HEAD should be |
| 65 | used for this (to accomodate for future changes). The implementation |
| 66 | of a particular object type can cast the object pointer to the proper |
| 67 | type and back. |
| 68 | |
| 69 | A standard interface exists for objects that contain an array of items |
| 70 | whose size is determined when the object is allocated. |
| 71 | |
| 72 | 123456789-123456789-123456789-123456789-123456789-123456789-123456789-12 |
| 73 | */ |
| 74 | |
Guido van Rossum | 3f5da24 | 1990-12-20 15:06:42 +0000 | [diff] [blame] | 75 | #ifndef NDEBUG |
| 76 | |
| 77 | /* Turn on heavy reference debugging */ |
| 78 | #define TRACE_REFS |
| 79 | |
| 80 | /* Turn on reference counting */ |
| 81 | #define REF_DEBUG |
| 82 | |
| 83 | #endif /* NDEBUG */ |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 84 | |
| 85 | #ifdef TRACE_REFS |
| 86 | #define OB_HEAD \ |
| 87 | struct _object *_ob_next, *_ob_prev; \ |
Guido van Rossum | c8564cd | 1990-11-02 17:51:56 +0000 | [diff] [blame] | 88 | int ob_refcnt; \ |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 89 | struct _typeobject *ob_type; |
| 90 | #define OB_HEAD_INIT(type) 0, 0, 1, type, |
| 91 | #else |
| 92 | #define OB_HEAD \ |
| 93 | unsigned int ob_refcnt; \ |
| 94 | struct _typeobject *ob_type; |
| 95 | #define OB_HEAD_INIT(type) 1, type, |
| 96 | #endif |
| 97 | |
| 98 | #define OB_VARHEAD \ |
| 99 | OB_HEAD \ |
| 100 | unsigned int ob_size; /* Number of items in variable part */ |
| 101 | |
| 102 | typedef struct _object { |
| 103 | OB_HEAD |
| 104 | } object; |
| 105 | |
| 106 | typedef struct { |
| 107 | OB_VARHEAD |
| 108 | } varobject; |
| 109 | |
| 110 | |
| 111 | /* |
| 112 | 123456789-123456789-123456789-123456789-123456789-123456789-123456789-12 |
| 113 | |
| 114 | Type objects contain a string containing the type name (to help somewhat |
| 115 | in debugging), the allocation parameters (see newobj() and newvarobj()), |
| 116 | and methods for accessing objects of the type. Methods are optional,a |
| 117 | nil pointer meaning that particular kind of access is not available for |
| 118 | this type. The DECREF() macro uses the tp_dealloc method without |
| 119 | checking for a nil pointer; it should always be implemented except if |
| 120 | the implementation can guarantee that the reference count will never |
| 121 | reach zero (e.g., for type objects). |
| 122 | |
| 123 | NB: the methods for certain type groups are now contained in separate |
| 124 | method blocks. |
| 125 | */ |
| 126 | |
| 127 | typedef struct { |
| 128 | object *(*nb_add) FPROTO((object *, object *)); |
| 129 | object *(*nb_subtract) FPROTO((object *, object *)); |
| 130 | object *(*nb_multiply) FPROTO((object *, object *)); |
| 131 | object *(*nb_divide) FPROTO((object *, object *)); |
| 132 | object *(*nb_remainder) FPROTO((object *, object *)); |
Guido van Rossum | 97ad2d8 | 1991-05-05 20:11:43 +0000 | [diff] [blame] | 133 | object *(*nb_divmod) FPROTO((object *, object *)); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 134 | object *(*nb_power) FPROTO((object *, object *)); |
| 135 | object *(*nb_negative) FPROTO((object *)); |
| 136 | object *(*nb_positive) FPROTO((object *)); |
Guido van Rossum | 97ad2d8 | 1991-05-05 20:11:43 +0000 | [diff] [blame] | 137 | object *(*nb_absolute) FPROTO((object *)); |
Guido van Rossum | cf7423a | 1991-05-14 12:08:10 +0000 | [diff] [blame] | 138 | int (*nb_nonzero) FPROTO((object *)); |
Guido van Rossum | 7a6dfa7 | 1991-10-24 14:58:18 +0000 | [diff] [blame] | 139 | object *(*nb_invert) FPROTO((object *)); |
| 140 | object *(*nb_lshift) FPROTO((object *, object *)); |
| 141 | object *(*nb_rshift) FPROTO((object *, object *)); |
| 142 | object *(*nb_and) FPROTO((object *, object *)); |
| 143 | object *(*nb_xor) FPROTO((object *, object *)); |
| 144 | object *(*nb_or) FPROTO((object *, object *)); |
Guido van Rossum | e6eefc2 | 1992-08-14 12:06:52 +0000 | [diff] [blame] | 145 | int (*nb_coerce) FPROTO((object **, object **)); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 146 | } number_methods; |
| 147 | |
| 148 | typedef struct { |
| 149 | int (*sq_length) FPROTO((object *)); |
| 150 | object *(*sq_concat) FPROTO((object *, object *)); |
| 151 | object *(*sq_repeat) FPROTO((object *, int)); |
| 152 | object *(*sq_item) FPROTO((object *, int)); |
| 153 | object *(*sq_slice) FPROTO((object *, int, int)); |
| 154 | int (*sq_ass_item) FPROTO((object *, int, object *)); |
| 155 | int (*sq_ass_slice) FPROTO((object *, int, int, object *)); |
| 156 | } sequence_methods; |
| 157 | |
| 158 | typedef struct { |
| 159 | int (*mp_length) FPROTO((object *)); |
| 160 | object *(*mp_subscript) FPROTO((object *, object *)); |
| 161 | int (*mp_ass_subscript) FPROTO((object *, object *, object *)); |
| 162 | } mapping_methods; |
| 163 | |
| 164 | typedef struct _typeobject { |
| 165 | OB_VARHEAD |
| 166 | char *tp_name; /* For printing */ |
| 167 | unsigned int tp_basicsize, tp_itemsize; /* For allocation */ |
| 168 | |
| 169 | /* Methods to implement standard operations */ |
| 170 | |
| 171 | void (*tp_dealloc) FPROTO((object *)); |
Guido van Rossum | d783a46 | 1991-06-07 22:35:42 +0000 | [diff] [blame] | 172 | int (*tp_print) FPROTO((object *, FILE *, int)); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 173 | object *(*tp_getattr) FPROTO((object *, char *)); |
| 174 | int (*tp_setattr) FPROTO((object *, char *, object *)); |
| 175 | int (*tp_compare) FPROTO((object *, object *)); |
| 176 | object *(*tp_repr) FPROTO((object *)); |
| 177 | |
| 178 | /* Method suites for standard classes */ |
| 179 | |
| 180 | number_methods *tp_as_number; |
| 181 | sequence_methods *tp_as_sequence; |
| 182 | mapping_methods *tp_as_mapping; |
| 183 | } typeobject; |
| 184 | |
| 185 | extern typeobject Typetype; /* The type of type objects */ |
| 186 | |
| 187 | #define is_typeobject(op) ((op)->ob_type == &Typetype) |
| 188 | |
Guido van Rossum | 3f5da24 | 1990-12-20 15:06:42 +0000 | [diff] [blame] | 189 | /* Generic operations on objects */ |
Guido van Rossum | d783a46 | 1991-06-07 22:35:42 +0000 | [diff] [blame] | 190 | extern int printobject PROTO((object *, FILE *, int)); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 191 | extern object * reprobject PROTO((object *)); |
| 192 | extern int cmpobject PROTO((object *, object *)); |
Guido van Rossum | 3f5da24 | 1990-12-20 15:06:42 +0000 | [diff] [blame] | 193 | extern object *getattr PROTO((object *, char *)); |
| 194 | extern int setattr PROTO((object *, char *, object *)); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 195 | |
| 196 | /* Flag bits for printing: */ |
| 197 | #define PRINT_RAW 1 /* No string quotes etc. */ |
| 198 | |
| 199 | /* |
| 200 | 123456789-123456789-123456789-123456789-123456789-123456789-123456789-12 |
| 201 | |
| 202 | The macros INCREF(op) and DECREF(op) are used to increment or decrement |
| 203 | reference counts. DECREF calls the object's deallocator function; for |
| 204 | objects that don't contain references to other objects or heap memory |
| 205 | this can be the standard function free(). Both macros can be used |
| 206 | whereever a void expression is allowed. The argument shouldn't be a |
| 207 | NIL pointer. The macro NEWREF(op) is used only to initialize reference |
| 208 | counts to 1; it is defined here for convenience. |
| 209 | |
| 210 | We assume that the reference count field can never overflow; this can |
| 211 | be proven when the size of the field is the same as the pointer size |
| 212 | but even with a 16-bit reference count field it is pretty unlikely so |
| 213 | we ignore the possibility. (If you are paranoid, make it a long.) |
| 214 | |
| 215 | Type objects should never be deallocated; the type pointer in an object |
| 216 | is not considered to be a reference to the type object, to save |
| 217 | complications in the deallocation function. (This is actually a |
| 218 | decision that's up to the implementer of each new type so if you want, |
| 219 | you can count such references to the type object.) |
| 220 | |
| 221 | *** WARNING*** The DECREF macro must have a side-effect-free argument |
| 222 | since it may evaluate its argument multiple times. (The alternative |
| 223 | would be to mace it a proper function or assign it to a global temporary |
| 224 | variable first, both of which are slower; and in a multi-threaded |
| 225 | environment the global variable trick is not safe.) |
| 226 | */ |
| 227 | |
| 228 | #ifdef TRACE_REFS |
| 229 | #ifndef REF_DEBUG |
| 230 | #define REF_DEBUG |
| 231 | #endif |
| 232 | #endif |
| 233 | |
| 234 | #ifndef TRACE_REFS |
| 235 | #define DELREF(op) (*(op)->ob_type->tp_dealloc)((object *)(op)) |
Guido van Rossum | d5b70f5 | 1990-11-18 17:27:10 +0000 | [diff] [blame] | 236 | #define UNREF(op) /*empty*/ |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 237 | #endif |
| 238 | |
| 239 | #ifdef REF_DEBUG |
| 240 | extern long ref_total; |
| 241 | #ifndef TRACE_REFS |
| 242 | #define NEWREF(op) (ref_total++, (op)->ob_refcnt = 1) |
| 243 | #endif |
| 244 | #define INCREF(op) (ref_total++, (op)->ob_refcnt++) |
| 245 | #define DECREF(op) \ |
Guido van Rossum | c8564cd | 1990-11-02 17:51:56 +0000 | [diff] [blame] | 246 | if (--ref_total, --(op)->ob_refcnt > 0) \ |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 247 | ; \ |
| 248 | else \ |
| 249 | DELREF(op) |
| 250 | #else |
| 251 | #define NEWREF(op) ((op)->ob_refcnt = 1) |
| 252 | #define INCREF(op) ((op)->ob_refcnt++) |
| 253 | #define DECREF(op) \ |
Guido van Rossum | c8564cd | 1990-11-02 17:51:56 +0000 | [diff] [blame] | 254 | if (--(op)->ob_refcnt > 0) \ |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 255 | ; \ |
| 256 | else \ |
| 257 | DELREF(op) |
| 258 | #endif |
| 259 | |
Guido van Rossum | 3f5da24 | 1990-12-20 15:06:42 +0000 | [diff] [blame] | 260 | /* Macros to use in case the object pointer may be NULL: */ |
| 261 | |
| 262 | #define XINCREF(op) if ((op) == NULL) ; else INCREF(op) |
| 263 | #define XDECREF(op) if ((op) == NULL) ; else DECREF(op) |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 264 | |
| 265 | /* Definition of NULL, so you don't have to include <stdio.h> */ |
| 266 | |
| 267 | #ifndef NULL |
| 268 | #define NULL 0 |
| 269 | #endif |
| 270 | |
| 271 | |
| 272 | /* |
| 273 | NoObject is an object of undefined type which can be used in contexts |
| 274 | where NULL (nil) is not suitable (since NULL often means 'error'). |
| 275 | |
| 276 | Don't forget to apply INCREF() when returning this value!!! |
| 277 | */ |
| 278 | |
| 279 | extern object NoObject; /* Don't use this directly */ |
| 280 | |
| 281 | #define None (&NoObject) |
| 282 | |
| 283 | |
| 284 | /* |
| 285 | 123456789-123456789-123456789-123456789-123456789-123456789-123456789-12 |
| 286 | |
| 287 | More conventions |
| 288 | ================ |
| 289 | |
| 290 | Argument Checking |
| 291 | ----------------- |
| 292 | |
| 293 | Functions that take objects as arguments normally don't check for nil |
| 294 | arguments, but they do check the type of the argument, and return an |
| 295 | error if the function doesn't apply to the type. |
| 296 | |
| 297 | Failure Modes |
| 298 | ------------- |
| 299 | |
| 300 | Functions may fail for a variety of reasons, including running out of |
Guido van Rossum | 3f5da24 | 1990-12-20 15:06:42 +0000 | [diff] [blame] | 301 | memory. This is communicated to the caller in two ways: an error string |
| 302 | is set (see errors.h), and the function result differs: functions that |
| 303 | normally return a pointer return NULL for failure, functions returning |
| 304 | an integer return -1 (which could be a legal return value too!), and |
| 305 | other functions return 0 for success and -1 for failure. |
| 306 | Callers should always check for errors before using the result. |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 307 | |
| 308 | Reference Counts |
| 309 | ---------------- |
| 310 | |
| 311 | It takes a while to get used to the proper usage of reference counts. |
| 312 | |
| 313 | Functions that create an object set the reference count to 1; such new |
| 314 | objects must be stored somewhere or destroyed again with DECREF(). |
| 315 | Functions that 'store' objects such as settupleitem() and dictinsert() |
| 316 | don't increment the reference count of the object, since the most |
| 317 | frequent use is to store a fresh object. Functions that 'retrieve' |
| 318 | objects such as gettupleitem() and dictlookup() also don't increment |
| 319 | the reference count, since most frequently the object is only looked at |
| 320 | quickly. Thus, to retrieve an object and store it again, the caller |
| 321 | must call INCREF() explicitly. |
| 322 | |
| 323 | NOTE: functions that 'consume' a reference count like dictinsert() even |
| 324 | consume the reference if the object wasn't stored, to simplify error |
| 325 | handling. |
| 326 | |
| 327 | It seems attractive to make other functions that take an object as |
| 328 | argument consume a reference count; however this may quickly get |
| 329 | confusing (even the current practice is already confusing). Consider |
| 330 | it carefully, it may safe lots of calls to INCREF() and DECREF() at |
| 331 | times. |
| 332 | |
| 333 | 123456789-123456789-123456789-123456789-123456789-123456789-123456789-12 |
| 334 | */ |