The simple-finalizer Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The simple-finalizer Reference Manual

This is the simple-finalizer Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:34:37 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

-*- mode: org -*-

* INTRODUCTION

This is the README for SIMPLE-FINALIZER, a package that wraps the 
finalizer functionality provided by TRIVIAL-GARBAGE and CFFI.

SIMPLE-FINALIZER depends on TRIVIAL-GARBAGE and CFFI.
 
ASDF packaging is provided; 

(asdf:oos 'asdf:load-op :simple-finalizer)

After loading the system, try the following example;
 
(make-instance 'simfin:foreign-object :fp (cffi:foreign-alloc :char :count 20))

(simfin:gc-p *)
(simfin:free **)

* DESCRIPTION

Simple-finalizer manages the deletion of a foreign object by implementing a wrapper object 
that contains both the foreign-object and the function to free the foreign object.
The foreign object may be deleted explictly by calling FREE, or automatically when the 
object is finalized (at time of garbage collection).

Use MAKE-INSTANCE to create a new FOREIGN-OBJECT, as show below.

(make-instance 'simfin:foreign-object :fp  :free  :gc )

FOREIGN-OBJECT wraps the foreign object stored in FP. The foreign object is finalized 
when the wrapper is garbage collected using the function in :FREE and :GC is T.

FP returns a reference to the foreign object or NIL if the object has already been 
deleted using FREE.

(simfin:FP *obj*)

The object can be explicitely freed using FREE. Once freed, the reference to the foreign 
object as well as the deletion function are set to NIL. Attempting to enable finalization
on a previously deleted foreign object will result in an error.

(simfin:FREE *obj*)

GC-P will return T if the object will be deleted at finalization/garbage collection.
Returns NIL if the foreign object was previously deleted or if the foreign object must 
be freed manually using FREE.

(simfin:GC-P *obj*)

FREE-P returns T if the foreign object was previously freed

(simfin:FREE-P *obj*)

Object deletion at finalization is enabled or disabled by setting GC-P to T or NIL, as follows;

(SETF (GC-P *obj*) T)   ; Enable finalization
(SETF (GC-P *obj*) NIL) ; Disable finalization

THIS-FP a reference to the foreign object. Unlike FP which can be overridden 
by a subclass, THIS-FP must never be overridden and must always point to the foreign object.

An important point to note is that the function passed in :FREE does not act as an object 
'destructor' in the C++ or Java sense because there are no destructors in Common Lisp. 
:FREE is not called when FOREIGN-OBJECT goes out of scope, but rather when the LISP
object is being garbage collected. Another point to note is that by the time the function 
in :FREE is called, the CLOS slots for the object will already have been garbage-collected.
  
Comments, criticisms, additions, and optimizations are welcome at the
email address below.
 
Luke Crook
luke@balooga.com


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 simple-finalizer

Maintainer

Luke Crook <luke@balooga.com>

Author

Luke Crook <luke@balooga.com>

License

BSD

Description

A simple Common Lisp finalizer for foreign objects when using CFFI and TRIVIAL-GARBAGE.

Version

0.1

Dependencies
Source

simple-finalizer.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 simple-finalizer.asd

Location

simple-finalizer.asd

Systems

simple-finalizer (system)

Packages

simple-finalizer-system


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 simple-finalizer/package.lisp

Parent

simple-finalizer (system)

Location

package.lisp

Packages

simple-finalizer


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 simple-finalizer/simple-finalizer.lisp

Dependency

package.lisp (file)

Parent

simple-finalizer (system)

Location

simple-finalizer.lisp

Exported Definitions
Internal Definitions

simple-free (function)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 simple-finalizer-system

Source

simple-finalizer.asd

Use List

Previous: , Up: Packages   [Contents][Index]

4.2 simple-finalizer

Source

package.lisp (file)

Nickname

simfin

Use List

common-lisp

Exported Definitions
Internal Definitions

simple-free (function)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Generic functions

Generic Function: fp OBJECT
Package

simple-finalizer

Methods
Method: fp (FOREIGN-OBJECT foreign-object)

Returns the foreign object reference.

Source

simple-finalizer.lisp (file)

Generic Function: free FOREIGN-OBJECT

An explicit cleanup method. When freed, ‘GC-P‘ will be NIL.

Package

simple-finalizer

Source

simple-finalizer.lisp (file)

Methods
Method: free (SELF foreign-object)
Generic Function: free-p FOREIGN-OBJECT

Returns ‘T if the foreign object was previously deleted using ‘FREE‘.

Package

simple-finalizer

Source

simple-finalizer.lisp (file)

Methods
Method: free-p (SELF foreign-object)
Generic Function: gc-p OBJECT
Package

simple-finalizer

Writer

(setf gc-p) (generic function)

Methods
Method: gc-p (FOREIGN-OBJECT foreign-object)

Returns ‘T‘ if the foreign object will be finalized.

Source

simple-finalizer.lisp (file)

Generic Function: (setf gc-p) VALUE FOREIGN-OBJECT

Enables or disables finalization.

Package

simple-finalizer

Source

simple-finalizer.lisp (file)

Reader

gc-p (generic function)

Methods
Method: (setf gc-p) VALUE (SELF foreign-object)
Generic Function: this-fp FOREIGN-OBJECT

Returns the foreign object reference. This method may not be redefined by a subclass.

Package

simple-finalizer

Source

simple-finalizer.lisp (file)

Methods
Method: this-fp (SELF foreign-object)

Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Classes

Class: foreign-object ()

A wrapper around the foreign object stored in ‘FP‘.
Finalizes the foreign object using the function in ‘:FREE‘ when ‘GC-P‘ is ‘T‘ when the wrapper is garbage collected. The foreign object is explicitely freed by calling ‘FREE‘.

Package

simple-finalizer

Source

simple-finalizer.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: foreign-pointer-to-object

Returns the foreign object reference.

Initargs

:fp

Initform

(error ":fp must not be nil.")

Readers

fp (generic function)

Slot: garbage-collect

Returns ‘T‘ if the foreign object will be finalized.

Initargs

:gc

Initform

t

Readers

gc-p (generic function)

Slot: free-function
Initargs

:free

Initform

(function cffi-sys:foreign-free)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: simple-free FUNC-FP TYPE
Package

simple-finalizer

Source

simple-finalizer.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, simple-finalizer.asd: The simple-finalizer<dot>asd file
File, Lisp, simple-finalizer/package.lisp: The simple-finalizer/package<dot>lisp file
File, Lisp, simple-finalizer/simple-finalizer.lisp: The simple-finalizer/simple-finalizer<dot>lisp file

L
Lisp File, simple-finalizer.asd: The simple-finalizer<dot>asd file
Lisp File, simple-finalizer/package.lisp: The simple-finalizer/package<dot>lisp file
Lisp File, simple-finalizer/simple-finalizer.lisp: The simple-finalizer/simple-finalizer<dot>lisp file

S
simple-finalizer.asd: The simple-finalizer<dot>asd file
simple-finalizer/package.lisp: The simple-finalizer/package<dot>lisp file
simple-finalizer/simple-finalizer.lisp: The simple-finalizer/simple-finalizer<dot>lisp file

Jump to:   F   L   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
F   G   M   S   T  
Index Entry  Section

(
(setf gc-p): Exported generic functions
(setf gc-p): Exported generic functions

F
fp: Exported generic functions
fp: Exported generic functions
free: Exported generic functions
free: Exported generic functions
free-p: Exported generic functions
free-p: Exported generic functions
Function, simple-free: Internal functions

G
gc-p: Exported generic functions
gc-p: Exported generic functions
Generic Function, (setf gc-p): Exported generic functions
Generic Function, fp: Exported generic functions
Generic Function, free: Exported generic functions
Generic Function, free-p: Exported generic functions
Generic Function, gc-p: Exported generic functions
Generic Function, this-fp: Exported generic functions

M
Method, (setf gc-p): Exported generic functions
Method, fp: Exported generic functions
Method, free: Exported generic functions
Method, free-p: Exported generic functions
Method, gc-p: Exported generic functions
Method, this-fp: Exported generic functions

S
simple-free: Internal functions

T
this-fp: Exported generic functions
this-fp: Exported generic functions

Jump to:   (  
F   G   M   S   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   F   G   S  
Index Entry  Section

F
foreign-pointer-to-object: Exported classes
free-function: Exported classes

G
garbage-collect: Exported classes

S
Slot, foreign-pointer-to-object: Exported classes
Slot, free-function: Exported classes
Slot, garbage-collect: Exported classes

Jump to:   F   G   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   P   S  
Index Entry  Section

C
Class, foreign-object: Exported classes

F
foreign-object: Exported classes

P
Package, simple-finalizer: The simple-finalizer package
Package, simple-finalizer-system: The simple-finalizer-system package

S
simple-finalizer: The simple-finalizer system
simple-finalizer: The simple-finalizer package
simple-finalizer-system: The simple-finalizer-system package
System, simple-finalizer: The simple-finalizer system

Jump to:   C   F   P   S