[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
gEDA-cvs: gaf.git: branch: master updated (1.7.2-20111231-12-gc15fecc)
The branch, master has been updated
via c15feccddc359d1ac3e62ed3b2182c7cc3aa938a (commit)
via 5cdf4de59028fad80072611a1194a4a8e224c363 (commit)
from 501d784118e135be1ead32b1233e64bc62e8d41e (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
=========
Summary
=========
libgeda/include/libgeda/libgedaguile.h | 3 +-
libgeda/include/libgedaguile_priv.h | 61 +++++++++++++++++++++++++++++++-
libgeda/src/scheme_init.c | 29 ++++++++++-----
libgeda/src/scheme_object.c | 6 ++-
libgeda/src/scheme_smob.c | 20 +++++++---
libgeda/src/scheme_toplevel.c | 5 ++-
6 files changed, 104 insertions(+), 20 deletions(-)
=================
Commit Messages
=================
commit c15feccddc359d1ac3e62ed3b2182c7cc3aa938a
Author: Peter TB Brett <peter@xxxxxxxxxxxxx>
Commit: Peter TB Brett <peter@xxxxxxxxxxxxx>
scheme-api: Improve doxygen docs for C API functions.
:100644 100644 b2f0712... 814b441... M libgeda/include/libgeda/libgedaguile.h
:100644 100644 229119b... 38dc17b... M libgeda/include/libgedaguile_priv.h
:100644 100644 01186a7... b4288a0... M libgeda/src/scheme_init.c
:100644 100644 47eb5b7... 77af5ac... M libgeda/src/scheme_object.c
:100644 100644 ef014a0... 999288f... M libgeda/src/scheme_smob.c
:100644 100644 7774522... 99e103b... M libgeda/src/scheme_toplevel.c
commit 5cdf4de59028fad80072611a1194a4a8e224c363
Author: Peter TB Brett <peter@xxxxxxxxxxxxx>
Commit: Peter TB Brett <peter@xxxxxxxxxxxxx>
scheme-api: Ensure init functions are called in Scheme mode.
This patch makes sure that any libguile functions called by
edascm_init() are called in Guile mode, even if for some reason
edascm_init() is called from a thread that is not yet in Guile mode.
:100644 100644 a9da63e... 01186a7... M libgeda/src/scheme_init.c
=========
Changes
=========
commit c15feccddc359d1ac3e62ed3b2182c7cc3aa938a
Author: Peter TB Brett <peter@xxxxxxxxxxxxx>
Commit: Peter TB Brett <peter@xxxxxxxxxxxxx>
scheme-api: Improve doxygen docs for C API functions.
diff --git a/libgeda/include/libgeda/libgedaguile.h b/libgeda/include/libgeda/libgedaguile.h
index b2f0712..814b441 100644
--- a/libgeda/include/libgeda/libgedaguile.h
+++ b/libgeda/include/libgeda/libgedaguile.h
@@ -1,6 +1,6 @@
/* gEDA - GPL Electronic Design Automation
* libgeda - gEDA's library - Scheme API
- * Copyright (C) 2010 Peter Brett <peter@xxxxxxxxxxxxx>
+ * Copyright (C) 2010-2012 Peter Brett <peter@xxxxxxxxxxxxx>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -19,6 +19,7 @@
/*!
* \file libgedaguile.h
+ * \ingroup guile_c_iface
* Scheme API public declarations and definitions.
* \warning Don't include from libgeda.h: should only be included
* by source files that need to use the Scheme API.
diff --git a/libgeda/include/libgedaguile_priv.h b/libgeda/include/libgedaguile_priv.h
index 229119b..38dc17b 100644
--- a/libgeda/include/libgedaguile_priv.h
+++ b/libgeda/include/libgedaguile_priv.h
@@ -1,6 +1,6 @@
/* gEDA - GPL Electronic Design Automation
* libgeda - gEDA's library - Scheme API
- * Copyright (C) 2010 Peter Brett <peter@xxxxxxxxxxxxx>
+ * Copyright (C) 2010-2012 Peter Brett <peter@xxxxxxxxxxxxx>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -17,6 +17,65 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
*/
+/*! \defgroup guile_c_iface gEDA Scheme API: C interface
+ * \brief Interface to the gEDA Scheme API for programs written in C.
+ *
+ * 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:
+ *
+ * \code
+ * 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 ();
+ * }
+ * \endcode
+ *
+ * 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.
+ */
+
/*!
* \file libgedaguile_priv.h
* Scheme API private declarations and definitions.
diff --git a/libgeda/src/scheme_init.c b/libgeda/src/scheme_init.c
index 01186a7..b4288a0 100644
--- a/libgeda/src/scheme_init.c
+++ b/libgeda/src/scheme_init.c
@@ -51,6 +51,7 @@ edascm_init_impl (void *data)
}
/*! \brief Initialise the Scheme API.
+ * \ingroup guile_c_iface
* \par Function Description
* Registers all modules, procedures and variables exported by the
* libgeda Scheme API.
diff --git a/libgeda/src/scheme_object.c b/libgeda/src/scheme_object.c
index 47eb5b7..77af5ac 100644
--- a/libgeda/src/scheme_object.c
+++ b/libgeda/src/scheme_object.c
@@ -1,6 +1,6 @@
/* gEDA - GPL Electronic Design Automation
* libgeda - gEDA's library - Scheme API
- * Copyright (C) 2010-2011 Peter Brett <peter@xxxxxxxxxxxxx>
+ * Copyright (C) 2010-2012 Peter Brett <peter@xxxxxxxxxxxxx>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -243,7 +243,9 @@ SCM_DEFINE (object_type, "%object-type", 1, 0, 0,
* list \a rst_s. The bounds are returned as a pair structure of the
* form:
*
- * <code>((left . top) . (right . bottom))</code>
+ * \code
+ * ((left . top) . (right . bottom))
+ * \endcode
*
* If \a rst_s is empty, or none of the objects has any bounds
* (e.g. because they are all empty components and/or text strings),
diff --git a/libgeda/src/scheme_smob.c b/libgeda/src/scheme_smob.c
index ef014a0..999288f 100644
--- a/libgeda/src/scheme_smob.c
+++ b/libgeda/src/scheme_smob.c
@@ -1,6 +1,6 @@
/* gEDA - GPL Electronic Design Automation
* libgeda - gEDA's library - Scheme API
- * Copyright (C) 2010 Peter Brett <peter@xxxxxxxxxxxxx>
+ * Copyright (C) 2010-2012 Peter Brett <peter@xxxxxxxxxxxxx>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -217,6 +217,7 @@ smob_equalp (SCM obj1, SCM obj2)
}
/*! \brief Get the smob for a TOPLEVEL.
+ * \ingroup guile_c_iface
* \par Function Description
* Create a new smob representing \a toplevel.
*
@@ -238,6 +239,7 @@ edascm_from_toplevel (TOPLEVEL *toplevel)
}
/*! \brief Get a smob for a page.
+ * \ingroup guile_c_iface
* \par Function Description
* Create a new smob representing \a page.
*
@@ -258,7 +260,8 @@ edascm_from_page (PAGE *page)
return smob;
}
-/* \brief Get a page from a smob.
+/*! \brief Get a page from a smob.
+ * \ingroup guile_c_iface
* \par Function Description
* Return the #PAGE represented by \a smob.
*
@@ -278,6 +281,7 @@ edascm_to_page (SCM smob)
}
/*! \brief Get a smob for a schematic object.
+ * \ingroup guile_c_iface
* \par Function Description
* Create a new smob representing \a object.
*
@@ -286,11 +290,11 @@ edascm_to_page (SCM smob)
* should set the garbage-collectable flag by calling:
*
* \code
- * SCM x = edascm_c_make_object (object);
+ * SCM x = edascm_from_object (object);
* edascm_c_set_gc (x, 1);
* \endcode
*
- * \fixme We currently have to bake a TOPLEVEL pointer into the smob,
+ * \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
@@ -315,7 +319,8 @@ edascm_from_object (OBJECT *object)
return smob;
}
-/* \brief Get a schematic object from a smob.
+/*! \brief Get a schematic object from a smob.
+ * \ingroup guile_c_iface
* \par Function Description
* Return the #OBJECT represented by \a smob.
*
@@ -335,13 +340,14 @@ edascm_to_object (SCM smob)
}
/*! \brief Set whether a gEDA object may be garbage collected.
+ * \ingroup guile_c_iface
* \par Function Description
* If \a gc is non-zero, allow the structure represented by \a smob to
* be destroyed when \a smob is garbage-collected.
*
* \param [in,out] smob Smob for which to set garbage-collection
* permission.
- * \param [in] x If non-zero, permit garbage collection.
+ * \param [in] gc If non-zero, permit garbage collection.
*/
void
edascm_c_set_gc (SCM smob, int gc)
@@ -351,6 +357,7 @@ edascm_c_set_gc (SCM smob, int gc)
}
/*! \brief Test whether a smob is a #OBJECT instance
+ * \ingroup guile_c_iface
* \par Function Description
* If \a smob is a #OBJECT instance, returns non-zero. Otherwise,
* returns zero.
@@ -366,6 +373,7 @@ edascm_is_object (SCM smob)
}
/*! \brief Test whether a smob is a #PAGE instance
+ * \ingroup guile_c_iface
* \par Function Description
* If \a smob is a #PAGE instance, returns non-zero. Otherwise,
* returns zero.
diff --git a/libgeda/src/scheme_toplevel.c b/libgeda/src/scheme_toplevel.c
index 7774522..99e103b 100644
--- a/libgeda/src/scheme_toplevel.c
+++ b/libgeda/src/scheme_toplevel.c
@@ -1,6 +1,6 @@
/* gEDA - GPL Electronic Design Automation
* libgeda - gEDA's library - Scheme API
- * Copyright (C) 2010 Peter Brett <peter@xxxxxxxxxxxxx>
+ * Copyright (C) 2010-2012 Peter Brett <peter@xxxxxxxxxxxxx>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -31,6 +31,7 @@ SCM scheme_toplevel_fluid = SCM_UNDEFINED;
/*!
* \brief Set the #TOPLEVEL fluid in the current dynamic context.
+ * \ingroup guile_c_iface
* \par Function Description
* This function must be used inside a pair of calls to
* scm_dynwind_begin() and scm_dynwind_end(). During the dynwind
@@ -61,6 +62,7 @@ SCM_DEFINE (edascm_current_toplevel, "%current-toplevel", 0, 0, 0,
/*!
* \brief Get the value of the #TOPLEVEL fluid.
+ * \ingroup guile_c_iface
* \par Function Description
* Return the value of the #TOPLEVEL fluid in the current dynamic
* context.
@@ -91,6 +93,7 @@ SCM_DEFINE (edascm_with_toplevel, "%with-toplevel", 2, 0, 0,
/*!
* \brief Set the current #TOPLEVEL temporarily.
+ * \ingroup guile_c_iface
* \par Function Description
* Set the #TOPLEVEL fluid to \a toplevel and call \a func with \a
* user_data.
commit 5cdf4de59028fad80072611a1194a4a8e224c363
Author: Peter TB Brett <peter@xxxxxxxxxxxxx>
Commit: Peter TB Brett <peter@xxxxxxxxxxxxx>
scheme-api: Ensure init functions are called in Scheme mode.
This patch makes sure that any libguile functions called by
edascm_init() are called in Guile mode, even if for some reason
edascm_init() is called from a thread that is not yet in Guile mode.
diff --git a/libgeda/src/scheme_init.c b/libgeda/src/scheme_init.c
index a9da63e..01186a7 100644
--- a/libgeda/src/scheme_init.c
+++ b/libgeda/src/scheme_init.c
@@ -1,6 +1,6 @@
/* gEDA - GPL Electronic Design Automation
* libgeda - gEDA's library - Scheme API
- * Copyright (C) 2010 Peter Brett <peter@xxxxxxxxxxxxx>
+ * Copyright (C) 2010-2012 Peter Brett <peter@xxxxxxxxxxxxx>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -31,17 +31,13 @@ static int init_called = 0;
SCM_GLOBAL_SYMBOL (edascm_object_state_sym, "object-state");
-/*! \brief Initialise the Scheme API.
+/*! \brief Scheme API initialisation worker function.
* \par Function Description
- * Registers all modules, procedures and variables exported by the
- * libgeda Scheme API.
+ * Called by edascm_init() with current thread in Guile mode.
*/
-void
-edascm_init ()
+static void
+edascm_init_impl (void *data)
{
- if (init_called) return;
- init_called = 1;
-
#include "scheme_init.x"
edascm_init_smob ();
@@ -53,3 +49,17 @@ edascm_init ()
edascm_init_os ();
edascm_init_deprecated ();
}
+
+/*! \brief Initialise the Scheme API.
+ * \par Function Description
+ * Registers all modules, procedures and variables exported by the
+ * libgeda Scheme API.
+ */
+void
+edascm_init ()
+{
+ if (init_called) return;
+ init_called = 1;
+
+ scm_with_guile (edascm_init_impl, NULL);
+}
_______________________________________________
geda-cvs mailing list
geda-cvs@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-cvs