Building Extensible Applications with Elk --
C/C++ Programmer's Manual

Oliver Laumann

ABSTRACT

Elk (Extension Language Kit) is a Scheme implementation designed as an embeddable, reusable extension language subsystem for integration into existing and future applications written in C or C++. The programmer's interface to Elk provides for a close interworking of the C/C++ parts of Elk-based, hybrid applications with extensible Scheme code. This manual describes the facilities of the C/C++ programmer's interface that can be used by authors of extensible applications and Scheme extensions. Topics range from the architecture of Elk-based applications and the definition of application-specific Scheme types and primitives to more advanced subjects such as weak data structures and interacting with the garbage collector. Many examples throughout the text illustrate the facilities and techniques discussed in this manual.

Table of Contents

• 1. Additional Documentation  
• 2. Introduction  
• 3. The Architecture of Extensible Applications  
  • 3.1. Scheme Extensions  
  • 3.2. Applications versus Extensions  
• 4. Linking Applications and Extensions with Elk  
• 5. Dynamic Loading  
  • 5.1. Load Libraries  
  • 5.2. Extension Initializers and Finalizers  
  • 5.3. C++ Static Constructors and Destructors  
• 6. Static Linking  
  • 6.1. Linking the Scheme Interpreter with Extensions  
    • 6.1.1. Automatic Extension Initialization  
  • 6.2. Linking the Scheme Interpreter with an Application  
    • 6.2.1. An Example ``main()'' Function  
  • 6.3. Who is in Control?  
• 7. Notes for Writing C/C++ Code Using Elk  
  • 7.1. Elk Include Files  
  • 7.2. Standard C and Function Prototypes  
  • 7.3. External Symbols Defined by Elk  
  • 7.4. Calling Scheme Primitives  
  • 7.5. Portable alloca()  
  • 7.6. Other Useful Macros and Functions  
• 8. The Anatomy of Scheme Objects  
  • 8.1. Type-specific Macros  
• 9. Defining New Scheme Primitives  
  • 9.1. Making Objects Known to the Garbage Collector  
  • 9.2. Primitives with Variable-Length Argument Lists  
• 10. Predefined Scheme Types  
  • 10.1. Booleans (T_Boolean)  
  • 10.2. Characters (T_Character)  
  • 10.3. Empty List (T_Null)  
  • 10.4. End of File (T_End_Of_File)  
  • 10.5. Integers (T_Fixnum and T_Bignum)  
  • 10.6. Floating Point Numbers (T_Flonum)  
  • 10.7. Pairs (T_Pair)  
  • 10.8. Symbols (T_Symbol)  
    • 10.8.1. The Non-Printing Symbol  
  • 10.9. Strings (T_String)  
  • 10.10. Vectors (T_Vector)  
  • 10.11. Ports (T_Port)  
  • 10.12. Miscellaneous Types  
• 11. Defining New Scheme Types  
  • 11.1. Example for a User-Defined Scheme Type  
• 12. Advanced Topics  
  • 12.1. Converting between Symbols, Integers, and Bitmasks  
  • 12.2. Calling Scheme Procedures, Evaluating Scheme Code  
  • 12.3. GC-Protecting Global Objects  
    • 12.3.1. Dynamic C Data Structures  
  • 12.4. Weak Pointers and Object Termination  
    • 12.4.1. Using Weak Pointers  
    • 12.4.2. Functions for Automatic Object Termination  
  • 12.5. Errors  
  • 12.6. Exceptions  
  • 12.7. Defining Scheme Variables  
  • 12.8. Defining Readers  
  • 12.9. Fork Handlers  
• 13. Appendix A: Functions that can Trigger a Garbage Collection  
• 14. Appendix B: Convenience Functions for GC-Safe Data Structures  
• 15. Appendix C: Summary of Functions, Macros, Types, and Variables  
• Footnotes