summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Benkard <code@mail.matthias.benkard.de>2008-03-05 15:48:20 +0100
committerMatthias Benkard <code@mail.matthias.benkard.de>2008-03-05 15:48:20 +0100
commit50acab3664ab433fe4d53a728097ea9132f6cf02 (patch)
tree3c288800deff92ce8560cb0d34ecb9558ba95c04
parent26ce314bd168d5f9865b850866ef9ac022125a49 (diff)
Document FOREIGN-VALUE-LISP-MANAGED-P and FOREIGN-VALUE-POINTER.
darcs-hash:28fe2a6f6d970312b95103a14631e6f58ee53635
-rw-r--r--Lisp/data-types.lisp82
1 files changed, 80 insertions, 2 deletions
diff --git a/Lisp/data-types.lisp b/Lisp/data-types.lisp
index 18f2611..1d460c9 100644
--- a/Lisp/data-types.lisp
+++ b/Lisp/data-types.lisp
@@ -269,8 +269,86 @@ an __exception__, you can simply send it the `self' message.
(defclass tagged-union (tagged-struct) ())
-;; FIXME: Document.
-(defgeneric foreign-value-lisp-managed-p (foreign-value))
+(defgeneric foreign-value-pointer (foreign-value)
+ (:documentation "Access the pointer to the foreign data wrapped by a __foreign-value__.
+
+## Arguments and Values:
+
+*foreign-value* --- an **object** of **type** __foreign-value__.
+
+Returns: a pointer.
+
+
+## Description:
+
+__foreign-value-pointer__ retrieves a system area pointer that points
+directly to the foreign data wrapped by *foreign-value*.
+
+Note that, by default, finalisation of a __foreign-value__ will cause
+the data pointed to to be deallocated. See
+__foreign-value-lisp-managed-p__ for details and how to control this
+behaviour if you need to.
+
+
+## See also:
+
+ __foreign-value-lisp-managed-p__, __foreign-value__, __foreign-struct__"))
+
+
+(defmethod foreign-value-pointer ((foreign-value foreign-value))
+ (pointer-to foreign-value))
+
+
+(defgeneric foreign-value-lisp-managed-p (foreign-value)
+ (:documentation "Determine or change whether a foreign value will be garbage-collected.
+
+_(setf foreign-value-lisp-managed-p)_ *managed-p* *foreign-value*
+
+## Arguments and Values:
+
+*foreign-value* --- an **object**.
+
+*managed-p* --- a **generalized boolean**.
+
+_foreign-value-lisp-managed-p_ returns: a **boolean**.
+
+
+## Description:
+
+When a value of a `struct` or `union` type is returned by a method call
+or given as an argument to a method implemented in Lisp, it is
+encapsulated in a __foreign-struct__ that by default deallocates the
+value upon its finalisation by the garbage collector.
+
+_foreign-value-lisp-managed-p_ determines whether this automatic
+deallocation is enabled. Setting _foreign-value-lisp-managed-p_ to
+**false** inhibits automatic deallocation of *foreign-value*.
+
+
+## Rationale:
+
+Having to manually deallocate all structs returned by values or passed
+as arguments to methods implemented in Lisp would require knowledge of
+whether a pointer or an actual struct was returned or passed,
+respectively. It would also prevent the user from simply discarding
+struct return values as any Lisp or Objective-C programmer could
+normally do without harm.
+
+On the other hand, automatic deallocation means that anytime the user
+wanted to save the struct in a foreign slot as a pointer, they would
+need to copy the struct first, which may be expensive and is certainly
+inconvenient.
+
+Doing the right thing therefore inevitably implies some kind of user
+action some of the time. Requiring the user to mark non-GCable objects
+seems like an acceptable trade-off.
+
+
+## See also:
+
+ __foreign-value__, __foreign-struct__"))
+
+
(defmethod foreign-value-lisp-managed-p ((foreign-value foreign-value))
(with-slots (lisp-managed-cell) foreign-value
(aref lisp-managed-cell)))