Interface to the gEDA Scheme API for programs written in C. More...

Files
file	libgedaguile.h
Functions
void	edascm_init ()
	Initialise the Scheme API.
SCM	edascm_from_toplevel (TOPLEVEL *toplevel)
	Get the smob for a TOPLEVEL.
SCM	edascm_from_page (PAGE *page)
	Get a smob for a page.
PAGE *	edascm_to_page (SCM smob)
	Get a page from a smob.
SCM	edascm_from_object (OBJECT *object)
	Get a smob for a schematic object.
OBJECT *	edascm_to_object (SCM smob)
	Get a schematic object from a smob.
void	edascm_c_set_gc (SCM smob, int gc)
	Set whether a gEDA object may be garbage collected.
int	edascm_is_object (SCM smob)
	Test whether a smob is a OBJECT instance.
int	edascm_is_page (SCM smob)
	Test whether a smob is a PAGE instance.
void	edascm_dynwind_toplevel (TOPLEVEL *toplevel)
	Set the TOPLEVEL fluid in the current dynamic context.
TOPLEVEL *	edascm_c_current_toplevel ()
	Get the value of the TOPLEVEL fluid.
SCM	edascm_c_with_toplevel (TOPLEVEL toplevel, SCM(func)(void ), void user_data)
	Set the current TOPLEVEL temporarily.

Detailed Description

This module contains a variety of functions for use in applications that use libgeda and which need to make use of or extend the gEDA Scheme API.

To initialise the API, edascm_init() needs to be called before any Scheme code is executed or any of the other functions listed in this module are called. Normally, this will be called automatically by libgeda_init().

The Scheme API requires a libgeda TOPLEVEL context to be available at any given time. The TOPLEVEL can be set on a per-thread basis using the edascm_dynwind_toplevel() or edascm_c_with_toplevel() functions. For example:

 static SCM worker (void *user_data)
 {
   // ...run Scheme code and/or call Scheme API C functions...
 }

 void myfunc(TOPLEVEL *toplevel)
 {
   void *mydata;

   // ...set up mydata... //

   // Set current toplevel using edascm_c_with_toplevel()
   edascm_c_with_toplevel (toplevel, worker, mydata);

   // Set current toplevel using dynamic wind
   scm_dynwind_begin (0);
   edascm_dynwind_toplevel (toplevel);
   worker (mydata);
   // ...run Scheme code and/or call Scheme API C functions...
   scm_dynwind_end ();
 }

For more information on dynamic wind, see the Guile Reference Manual.

The remaining functions in this module allow you to convert gEDA OBJECT and PAGE structures to and from Scheme values ("smobs").

When an OBJECT is created by Scheme code, it is permitted to be garbage-collected if all references to it are lost; this is an important part of allowing Scheme programmers to write efficient code. However, because OBJECT instances are not reference counted, each Scheme object that contains an OBJECT has a flag that indicates whether it is wholly owned by Scheme or whether there are any remaining references to it from C code. If you use edascm_from_object() to create a Scheme value for an OBJECT that has no remaining references from other C structures, you should use edascm_c_set_gc() to mark it as garbage-collectable.

Function Documentation

void edascm_init ( )

Function Description: Registers all modules, procedures and variables exported by the libgeda Scheme API.

Definition at line 61 of file scheme_init.c.

Here is the call graph for this function:

SCM edascm_from_toplevel ( TOPLEVEL * toplevel )

Function Description: Create a new smob representing toplevel.

Parameters:

toplevel TOPLEVEL to create a smob for.

Returns:: a smob representing toplevel.

Definition at line 228 of file scheme_smob.c.

Here is the call graph for this function:

SCM edascm_from_page ( PAGE * page )

Function Description: Create a new smob representing page.

Parameters:

page	PAGE to create a smob for.

Returns:: a smob representing page.

Definition at line 250 of file scheme_smob.c.

Here is the call graph for this function:

PAGE* edascm_to_page ( SCM smob )

Function Description: Return the PAGE represented by smob.

Parameters:

[in] smob Guile value to retrieve PAGE from.

Returns:: the PAGE represented by smob.

Definition at line 272 of file scheme_smob.c.

SCM edascm_from_object ( OBJECT * object )

Function Description: Create a new smob representing object.

Warning:: The returned smob is initially marked as owned by the C code. If it should be permitted to be garbage-collected, you should set the garbage-collectable flag by calling:

   SCM x = edascm_from_object (object);
   edascm_c_set_gc (x, 1);

Note:: We currently have to bake a TOPLEVEL pointer into the smob, so that if the object becomes garbage-collectable we can obtain a TOPLEVEL to use for deleting the smob without accessing the TOPLEVEL fluid and potentially causing a race condition (see bug 909358).

Parameters:

object OBJECT to create a smob for.

Returns:: a smob representing object.

Definition at line 307 of file scheme_smob.c.

Here is the call graph for this function:

OBJECT* edascm_to_object ( SCM smob )

Function Description: Return the OBJECT represented by smob.

Parameters:

[in] smob Guile value to retrieve OBJECT from.

Returns:: the OBJECT represented by smob.

Definition at line 331 of file scheme_smob.c.

void edascm_c_set_gc	(	SCM	smob,
		int	gc
	)

Function Description: If gc is non-zero, allow the structure represented by smob to be destroyed when smob is garbage-collected.

Parameters:

[in,out]	smob	Smob for which to set garbage-collection permission.
[in]	gc	If non-zero, permit garbage collection.

Definition at line 353 of file scheme_smob.c.

int edascm_is_object ( SCM smob )

Function Description: If smob is a OBJECT instance, returns non-zero. Otherwise, returns zero.

Parameters:

[in] smob Guile value to test.

Returns:: non-zero iff smob is a OBJECT instance.

Definition at line 370 of file scheme_smob.c.

int edascm_is_page ( SCM smob )

Function Description: If smob is a PAGE instance, returns non-zero. Otherwise, returns zero.

Parameters:

[in] smob Guile value to test.

Returns:: non-zero iff smob is a PAGE instance.

Definition at line 386 of file scheme_smob.c.

void edascm_dynwind_toplevel ( TOPLEVEL * toplevel )

Function Description: This function must be used inside a pair of calls to scm_dynwind_begin() and scm_dynwind_end(). During the dynwind context, the TOPLEVEL fluid is set to toplevel.

Note:: This is a part of the public C interface to the Scheme API.

Definition at line 43 of file scheme_toplevel.c.

Here is the call graph for this function:

TOPLEVEL* edascm_c_current_toplevel ( )

Function Description: Return the value of the TOPLEVEL fluid in the current dynamic context.

Note:: This is a part of the public C interface to the Scheme API.

Definition at line 73 of file scheme_toplevel.c.

SCM edascm_c_with_toplevel	(	TOPLEVEL *	toplevel,
		SCM()(void )	func,
		void *	user_data
	)

Function Description: Set the TOPLEVEL fluid to toplevel and call func with user_data.

Definition at line 102 of file scheme_toplevel.c.

Here is the call graph for this function:

gEDA Scheme API: C interface

Files

Functions

Detailed Description

Function Documentation