New patches: [review Foreign Types; add Glossary Stephen Compall **20060613205550] < > { hunk ./doc/cffi-manual.texinfo 158 * Finalizers:: * Limitations:: * Platform-specific features:: Details about the underlying system. +* Glossary:: List of CFFI-specific terms and meanings. * Comprehensive Index:: @detailmenu hunk ./doc/cffi-manual.texinfo 2373 A documentation string, ignored. @item slot-name -A symbol naming the slot. +A symbol naming the slot. It must be unique among slot names in this +structure. @item size Use this option to override the size (in bytes) of the struct. hunk ./doc/cffi-manual.texinfo 2384 @item count Used to declare an array of size @var{count} inside the -structure. +structure. Defaults to @code{1} as such an array and a single element +are semantically equivalent. @item offset hunk ./doc/cffi-manual.texinfo 2388 -Overrides the slot's offset. The next slot's offset is calcultated +Overrides the slot's offset. The next slot's offset is calculated based on this one. @end table hunk ./doc/cffi-manual.texinfo 2393 @subheading Description -A structure slot is either simple or aggregate. +This defines a new @cffi{} aggregate type akin to C @code{struct}s. +In other words, it specifies that foreign objects of the type +@var{structure-name} are groups of different pieces of data, or +``slots'', of the @var{slot-type}s, distinguished from each other by +the @var{slot-name}s. Each structure is located in memory at a +position, and the slots are allocated sequentially beginning at that +point in memory (with some padding allowances as defined by the C +@acronym{ABI}, unless otherwise requested by specifying an +@var{offset} from the beginning of the structure (offset 0). hunk ./doc/cffi-manual.texinfo 2403 -Simple structure slots contain a single instance of a type that -canonicalizes to a built-in type, such as @code{:long} or -@code{:pointer}. +In other words, it is isomorphic to the C @code{struct}, giving +several extra features. hunk ./doc/cffi-manual.texinfo 2406 -Aggregate slots contain an embedded structure or union, or an array -of objects. +There are two kinds of slots, for the two kinds of @cffi{} types: hunk ./doc/cffi-manual.texinfo 2408 +@table @dfn +@item Simple +Contain a single instance of a type that canonicalizes to a built-in +type, such as @code{:long} or @code{:pointer}. Used for simple +@cffi{} types. + +@item Aggregate +Contain an embedded structure or union, or an array of objects. Used +for aggregate @cffi{} types. +@end table + +The use of @acronym{CLOS} terminology for the structure-related +features is intentional; structure definitions are very much like +classes with (far) fewer features. + @subheading Examples @lisp (defcstruct point hunk ./doc/cffi-manual.texinfo 2496 @end table @subheading Description -A union is a structure in which all slots have an offset of -zero. Therefore, you should use the usual foreign structure operations -for accessing a union's slots. +A union is a structure in which all slots have an offset of zero. It +is isomorphic to the C @code{union}. Therefore, you should use the +usual foreign structure operations for accessing a union's slots. @subheading Examples @lisp hunk ./doc/cffi-manual.texinfo 2754 @table @var @item type -A @code{bitfield} type. +A bitfield type. @item value An integer. hunk ./doc/cffi-manual.texinfo 2760 @item symbols -A list of symbols. +A potentially shared list of symbols. @code{nil}. @end table hunk ./doc/cffi-manual.texinfo 2765 @subheading Description -The function @code{foreign-bitfield-symbols} returns the Lisp symbol -that corresponds to @var{value} in @var{type}. +The function @code{foreign-bitfield-symbols} returns a possibly shared +list of symbols that correspond to @var{value} in @var{type}. @subheading Examples @lisp hunk ./doc/cffi-manual.texinfo 2940 @end table @subheading Description -The function @code{foreign-slot-names} returns a list of symbols that denote -the foreign slots of a struct type. This list has no particular order. +The function @code{foreign-slot-names} returns a potentially shared +list of slot @var{names} for the given structure @var{type}. This list +has no particular order. @subheading Examples @lisp hunk ./doc/cffi-manual.texinfo 3011 @node foreign-slot-pointer @unnumberedsec foreign-slot-pointer @subheading Syntax -@Function{foreign-slot-pointer ptr type &rest slot-names => pointer} +@Function{foreign-slot-pointer ptr type slot-name => pointer} @subheading Arguments and Values hunk ./doc/cffi-manual.texinfo 3023 A foreign structure type. @item slot-names -One or more slot names. +A slot name in the @var{type}. @item pointer hunk ./doc/cffi-manual.texinfo 3026 -A pointer to the slot specified in @var{slot-names}. +A pointer to the slot @var{slot-name}. @end table @subheading Description hunk ./doc/cffi-manual.texinfo 3030 -Returns a pointer to a slot referred by @var{slot-names} in a foreign -object of type @var{type} at @var{ptr}. The returned pointer points -inside the structure. Both the pointer and the memory it points to -have the same extent as @var{ptr}. +Returns a pointer to the location of the slot @var{slot-name} in a +foreign object of type @var{type} at @var{ptr}. The returned pointer +points inside the structure. Both the pointer and the memory it points +to have the same extent as @var{ptr}. For aggregate slots, this is the same value returned by @code{foreign-slot-value}. hunk ./doc/cffi-manual.texinfo 3187 @subheading Description The function @code{foreign-type-size} return the @var{size} of -@var{type} in bytes. +@var{type} in bytes. This includes any padding within and following +the in-memory representation as needed to create an array of +@var{type} objects. @subheading Examples @lisp hunk ./doc/cffi-manual.texinfo 3326 arguments to a callback function, or accessing a foreign variable. To extend the @cffi{} type system by performing custom translations, this -method may be specialized by EQL-specializing @code{type-name} on a +method may be specialized by @sc{eql}-specializing @code{type-name} on a symbol naming a foreign type defined with @code{defctype}. This method should return the appropriate Lisp value to use in place of the foreign value. hunk ./doc/cffi-manual.texinfo 3332 The results are undefined if the @code{type-name} parameter is -specialized in any way except an EQL specializer on a foreign type +specialized in any way except an @sc{eql} specializer on a foreign type defined with @code{defctype}. Specifically, translations may not be defined for built-in types. hunk ./doc/cffi-manual.texinfo 3355 @table @var @item lisp-value -The lisp value to convert to foreign representation. +The Lisp value to convert to foreign representation. @item type-name A symbol naming a foreign type defined by @code{defctype}. hunk ./doc/cffi-manual.texinfo 3371 @subheading Description This generic function is invoked by @cffi{} to convert a Lisp value to a foreign value, such as when passing arguments to a foreign function, -returning a value from a callback, or setting a foreign variable. +returning a value from a callback, or setting a foreign variable. A +``foreign value'' is one appropriate for passing to the next-lowest +translator, including the low-level translators that are ultimately +invoked invisibly with @cffi{}. To extend the @cffi{} type system by performing custom translations, this hunk ./doc/cffi-manual.texinfo 3377 -method may be specialized by EQL-specializing @code{type-name} on a +method may be specialized by @sc{eql}-specializing @code{type-name} on a symbol naming a foreign type defined with @code{defctype}. This method should return the appropriate foreign value to use in place of the Lisp value. hunk ./doc/cffi-manual.texinfo 3391 deallocation methods. The results are undefined if the @code{type-name} parameter is -specialized in any way except an EQL specializer on a foreign type +specialized in any way except an @sc{eql} specializer on a foreign type defined with @code{defctype}. Specifically, translations may not be defined for built-in types. hunk ./doc/cffi-manual.texinfo 3428 @subheading Description The @code{with-foreign-slots} macro creates local symbol macros for each var in @var{vars} to reference foreign slots in @var{ptr} of -@var{type}. It is similar to Common Lisp's @code{with-slots} macro. +@var{type}. It is similar to Common Lisp's @code{with-slots} macro. @subheading Examples @lisp hunk ./doc/cffi-manual.texinfo 3451 (foreign-funcall "gmtime" :pointer time tm)) @result{} # CFFI> (with-foreign-slots ((sec min hour mday mon year) * tm) - (format nil "~A:~A:~A, ~A/~A/~A" hour min sec (+ 1900 year) mon mday)) + (format nil "~A:~A:~A, ~A/~A/~A" + hour min sec (+ 1900 year) mon mday)) @result{} "7:22:47, 2005/8/2" @end lisp hunk ./doc/cffi-manual.texinfo 5596 processors from Intel or @acronym{AMD}. @end table + +@node Glossary +@appendix Glossary + +@table @dfn +@item aggregate type +A @cffi{} type for C data defined as an organization of data of simple +type; in structures and unions, which are themselves aggregate types, +they are represented by value. + +@item foreign value +This has two meanings; in any context, only one makes sense. + +When using type translators, the foreign value is the lower-level Lisp +value derived from the object passed to @code{translate-to-foreign} +(@pxref{translate-to-foreign}). This value should be a Lisp number or +a pointer (satisfies @code{pointerp}), and it can be treated like any +general Lisp object; it only completes the transformation to a true +foreign value when passed through low-level code in the Lisp +implementation, such as the foreign function caller or indirect memory +addressing combined with a data move. + +In other contexts, this refers to a value accessible by C, but which +may only be accessed through @cffi{} functions. The closest you can +get to such a foreign value is through a pointer Lisp object, which +itself counts as a foreign value in only the previous sense. + +@item simple type +A @cffi{} type that is ultimately represented as a builtin type; +@cffi{} only provides extra semantics for Lisp that are invisible to C +code or data. +@end table @node Comprehensive Index @unnumbered Index } Context: [Run tests both compiled and uncompiled. Luis Oliveira **20060607183000 - Make the test-suite run both with and without rt::*compile-tests* bound to T. ] [Huh. Found a very old and incomplete sentence in the manual. Luis Oliveira **20060607022358] [Minor comestic change in foreign-vars.lisp Luis Oliveira **20060607022335] [Lispworks bugfix: %mem-ref and %mem-set compiler macros Luis Oliveira **20060607022325 - The %mem-ref and %mem-set in cffi-lispworks.lisp were using bogus indexes. FLI's documentation suggests foreign-typed-aref expects array indexes but it seems to want offsets in bytes instead. - Regression tests: mem-ref.rt.1 and mem-ref.rt.2. ] [bugfix: accept symbols in defcvar Luis Oliveira **20060527020411 - Fix lisp-var-name to accept symbols. - Regression test: foreign-globals.symbol-name ] [Minor simplification in tests/bindings.lisp Luis Oliveira **20060526113626] [Fix some ECL bugs (maybe) Luis Oliveira **20060526113437 - Fixed some bitrot in cffi-ecl.lisp (maybe). Still can't test properly because of an ECL bug related to make-load-form. ] [Fix uffi-compat bugs Luis Oliveira **20060520181344 - :pointer is no longer a built-in type so we have to parse it, not find-type it. - def-array-pointer actually defines an array type with 1 element. (this emulates UFFI's behaviour) Bug report and initial patches courtesy of Lou Vanek. ] [Fix problem with declarations in DEFCALLBACKs Luis Oliveira **20060514234218 - Place declarations after the translations take place. - We no longer poke at ignore declarations in defcallback. ] [change first automatic defbitfield value to 1 Stephen Compall **20060512153832 - make-foreign-bitfield now starts implicit bitfield values at 1. No more special cases for zero. - Document and update bf tests to match. ] [defbitfield: explicit initial zero case Stephen Compall **20060511162202 - Provide for counting an initial zero as a pseudo-single-bit. - Test bitfield.4. ] [only single-bits affect defbitfield implicit values Stephen Compall **20060511154221 - Remove a case in which a non-single-bit like 3 could hijack the implicit value computation for defbitfield. - New test bitfield.3 for this behavior. ] [Fix defbitfield bug and new test Luis Oliveira **20060511145035 - Bug fix: when the first value was provided a (< foo nil) comparision would occur. Regresion test: bitfield.1. - New test bitfield.2. ] [implicit defbitfield symbol values Stephen Compall **20060511072106 - Foreign Type Translators: defctype does not create Lisp types; you have to use eql specializers. - enum.lisp: Use reduce in %foreign-bitfield-value. Code a default rule for bitfield symbol values. ] [Make :POINTER a parameterized foreign type. James Bielman **20060507003511 - :POINTER without arguments is a void pointer. - (:POINTER :INT) is a pointer to an :INT. - These nest properly: (:POINTER (:POINTER :INT)). - Pointers are not type checked yet---an optional pointer type checker will be added someday. ] [Bugfix: Quote type arguments to %DEFCFUN-VARARGS. James Bielman **20060507002829] [Recognize OpenMCL/X86-64 and set CFFI features accordingly. James Bielman **20060504173940] [Conditionalize against non-CPU specific word-size features in OpenMCL. James Bielman **20060504021623] [Bugfix: Specialize UNPARSE for UFFI-CHAR in CFFI-UFFI-COMPAT. James Bielman **20060504015421 - Fixes an error when loading FASL files that dumped UFFI-CHAR instead of (UFFI-CHAR :CHAR) using MAKE-LOAD-FORM. - Reported by Ricardo Boccato. ] [More copyright header year updates. James Bielman **20060503064225] [Update copyright year in file headers. James Bielman **20060503063944] [Conditionally set variables for implementations in Makefile. James Bielman **20060503063241 - Allow overriding from the environment as suggest in the comment, which didn't actually work. (eg.: OPENMCL=openmcl64 make test) ] [Add OpenMCL/X86-64 fasl files to 'make clean'. James Bielman **20060503061637] [Make corman's finalizers thread-safe (hopefully) Luis Oliveira **20060424173620] [Add support for finalizers Luis Oliveira **20060424025357 - New functions: finalize and cancel-finalization. - New cffi-"feature": no-finalizers. Only ECL pushes this. - Document new functions. ] [Include stdint.h in libtest.c Luis Oliveira **20060424025320] [Oops, forgot to bump the version number. Luis Oliveira **20060424025119] [TAG 0.9.1 Luis Oliveira **20060418011351] Patch bundle hash: 9d68fb8d8b20b13d1701f3c29b5314a7120490cb