This is the mail archive of the guile@cygnus.com mailing list for the guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: gh_defer_ints documentation?


"Steven G. Johnson" <stevenj@alum.mit.edu> writes:

> What exactly is gh_defer_ints() useful for?  It is called by the tutorial
> program, but I can't find much documentation on it, except that it
> "disables Guile interrupts."

This is exactly what it does.  It should occur at the beginning of a
piece of code that breaks if it is interrupted.

Example: code which alters the state of the heap by manipulating heap
cells directly using pointers instead of library functions.

The region of code should be terminated by a call to gh_allow_ints().

> Why is Guile interrupting my code,

The most common situation is that the user presses CTRL-C.  Other
examples is: you have set up a timer signalling the process.

> will gh_defer_ints make much difference in runtime for a function
> that takes a long time to run?

gh_defer_ints/gh_allow_ints are very cheap to execute (they aren't
even real function calls, they are macros).  It is even a good
strategy to make sure to execute these functions each turn in
long-running loops since a threaded Guile uses calls to gh_allow_ints
as context switch points.

> Are the interrupts so that Guile can do garbage-collection?

No.  Interrupts occur due to the same reasons as usual in most
programs (CTRL-C, timer etc).

> If so, should I worry that objects I create in my C program will be
> swept out from under me before I get a chance to pass them back to
> my Guile program?

gh_defer_ints/gh_allow_ints has nothing to do with GC.  Objects which
are referred to from the heap or directly by C variables are always
safe.  However, you must explicitly tell the GC about objects which
aren't referred to diectly from C variables, i.e., objects stored in
data structures outside the heap.

The library functions to do this are:

scm_protect_object
scm_unprotect_object
scm_permanent_object

> I wish the documentation were more complete.

Me too...

/mdj