From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Andy Wingo Newsgroups: gmane.lisp.guile.bugs Subject: bug#20907: [PATCH] Manual bug for scm_gc_protect_object Date: Fri, 24 Jun 2016 08:58:53 +0200 Message-ID: <8760szjcnm.fsf@pobox.com> References: <87h9nc1ytx.fsf@netris.org> <1832189928.562370.1441218868076.JavaMail.yahoo@mail.yahoo.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: ger.gmane.org 1466751687 22937 80.91.229.3 (24 Jun 2016 07:01:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 24 Jun 2016 07:01:27 +0000 (UTC) Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , 20907-done@debbugs.gnu.org To: Mike Gran Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Fri Jun 24 09:01:17 2016 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bGL74-0007cj-G8 for guile-bugs@m.gmane.org; Fri, 24 Jun 2016 09:01:14 +0200 Original-Received: from localhost ([::1]:41437 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGL73-0008Vn-Ly for guile-bugs@m.gmane.org; Fri, 24 Jun 2016 03:01:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38590) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGL61-0007tH-N6 for bug-guile@gnu.org; Fri, 24 Jun 2016 03:00:11 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bGL5u-00054q-Nn for bug-guile@gnu.org; Fri, 24 Jun 2016 03:00:08 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:40918) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bGL5u-00054g-KW for bug-guile@gnu.org; Fri, 24 Jun 2016 03:00:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bGL5u-0007sf-AI for bug-guile@gnu.org; Fri, 24 Jun 2016 03:00:02 -0400 Resent-From: Andy Wingo Original-Sender: "Debbugs-submit" Resent-To: bug-guile@gnu.org Resent-Date: Fri, 24 Jun 2016 07:00:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: cc-closed 20907 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch Mail-Followup-To: 20907@debbugs.gnu.org, wingo@pobox.com, spk121@yahoo.com Original-Received: via spool by 20907-done@debbugs.gnu.org id=D20907.146675154830202 (code D ref 20907); Fri, 24 Jun 2016 07:00:02 +0000 Original-Received: (at 20907-done) by debbugs.gnu.org; 24 Jun 2016 06:59:08 +0000 Original-Received: from localhost ([127.0.0.1]:53255 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bGL51-0007r3-W6 for submit@debbugs.gnu.org; Fri, 24 Jun 2016 02:59:08 -0400 Original-Received: from pb-sasl2.pobox.com ([64.147.108.67]:63795 helo=sasl.smtp.pobox.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bGL4x-0007qp-Ee for 20907-done@debbugs.gnu.org; Fri, 24 Jun 2016 02:59:06 -0400 Original-Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by pb-sasl2.pobox.com (Postfix) with ESMTP id E4C1920368; Fri, 24 Jun 2016 02:59:01 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=//Uo14zgmOddtBV/zuSb8tb9XJU=; b=nmmIyP 5Om6zs1Y3nRGBQhJZe6Csh15LoJr2yF+EmBqP53VJ5JzzlpmQI7AZGir8EkIAZqi UzSuVEETmmrTts78tqxIFzsybrHLK7R1lOHZoACs6B9ZR4rsWqPuRnIoL0odhfex zB25vu2qoft4BauWHXFYuK6jKJRhSukDf229o= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; q=dns; s=sasl; b=IyjoEgP6oiEbAUm7/Aak6kOsLEXARL2g ci6zKgrqI3d/WW9j8TOCBj2q5oCqk7rWQ7o6Jq54F8oQX397sE9Iha6Y9xUf0nmE bmDXgsTqh3ESOHsAMWT8K5JmiAaqEHioFL4pPRCR30VktGNPwUFVJEbx1Iz/urlo xG2liL3ljuc= Original-Received: from pb-sasl2.nyi.icgroup.com (unknown [127.0.0.1]) by pb-sasl2.pobox.com (Postfix) with ESMTP id DC1BB20367; Fri, 24 Jun 2016 02:59:01 -0400 (EDT) Original-Received: from clucks (unknown [88.160.190.192]) (using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by pb-sasl2.pobox.com (Postfix) with ESMTPSA id 5470620363; Fri, 24 Jun 2016 02:59:00 -0400 (EDT) In-Reply-To: <1832189928.562370.1441218868076.JavaMail.yahoo@mail.yahoo.com> (Mike Gran's message of "Wed, 2 Sep 2015 18:34:28 +0000 (UTC)") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) X-Pobox-Relay-ID: 2109BB60-39D9-11E6-8E3F-28A6F1301B6D-02397024!pb-sasl2.pobox.com X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Original-Sender: "bug-guile" Xref: news.gmane.org gmane.lisp.guile.bugs:8199 Archived-At: --=-=-= Content-Type: text/plain On Wed 02 Sep 2015 20:34, Mike Gran writes: > On Wednesday, September 2, 2015 11:06 AM, Mark H Weaver wrote: > >>Would it help to replace all uses of the term "scan" with "mark", in >>connection with garbage collection? In the papers I've read on GC, >>"mark" is the word I usually see, and it seems much clearer to me, >>because anyone who knows the basics of GC knows that "marking" is needed >>to prevent an object from being freed, whereas "scanning" could mean >>anything. > > That would help, I think. I guess I was associating "scan" with > the "sweep" part of mark and sweep. > > Thanks very much for the clarification. I think "scanning" is a term that is used sometimes, like tracing or visiting. But it's true that in the case of the manual it was used without much context. I made some tweaks that hopefully clarify things, enough to close this bug anyway :) Andy --=-=-= Content-Type: text/plain Content-Disposition: inline; filename=0001-Clarify-use-of-the-term-scanning-in-the-manual.patch >From f84006c5644997ce9854df9070ec2f1fb8acd420 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Fri, 24 Jun 2016 08:56:21 +0200 Subject: [PATCH] Clarify use of the term "scanning" in the manual * doc/ref/api-memory.texi (Garbage Collection Functions): * doc/ref/libguile-concepts.texi (Garbage Collection): Attempt to be clear that scanning is a thing that happens in the mark phase. Fixes #20907 I think. --- doc/ref/api-memory.texi | 42 ++++++++++++++++++++---------------- doc/ref/libguile-concepts.texi | 48 ++++++++++++++++++++++++++++-------------- 2 files changed, 56 insertions(+), 34 deletions(-) diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi index 142eb01..ce0187b 100644 --- a/doc/ref/api-memory.texi +++ b/doc/ref/api-memory.texi @@ -27,9 +27,10 @@ collection relates to using Guile from C. @deffn {Scheme Procedure} gc @deffnx {C Function} scm_gc () -Scans all of SCM objects and reclaims for further use those that are -no longer accessible. You normally don't need to call this function -explicitly. It is called automatically when appropriate. +Finds all of the ``live'' @code{SCM} objects and reclaims for further +use those that are no longer accessible. You normally don't need to +call this function explicitly. Its functionality is invoked +automatically as needed. @end deffn @deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj}) @@ -43,8 +44,9 @@ than it has been protected. Returns the SCM object it was passed. Note that storing @var{obj} in a C global variable has the same effect@footnote{In Guile up to version 1.8, C global variables were not -scanned by the garbage collector; hence, @code{scm_gc_protect_object} -was the only way in C to prevent a Scheme object from being freed.}. +visited by the garbage collector in the mark phase; hence, +@code{scm_gc_protect_object} was the only way in C to prevent a Scheme +object from being freed.}. @end deftypefn @deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj}) @@ -123,16 +125,18 @@ live reference to it@footnote{In Guile up to version 1.8, memory allocated with @code{scm_gc_malloc} @emph{had} to be freed with @code{scm_gc_free}.}. -Memory allocated with @code{scm_gc_malloc} is scanned for live pointers. -This means that if @code{scm_gc_malloc}-allocated memory contains a -pointer to some other part of the memory, the garbage collector notices -it and prevents it from being reclaimed@footnote{In Guile up to 1.8, -memory allocated with @code{scm_gc_malloc} was @emph{not} scanned. -Consequently, the GC had to be told explicitly about pointers to live -objects contained in the memory block, e.g., @i{via} SMOB mark functions -(@pxref{Smobs, @code{scm_set_smob_mark}})}. Conversely, memory -allocated with @code{scm_gc_malloc_pointerless} is assumed to be -``pointer-less'' and is not scanned. +When garbage collection occurs, Guile will visit the words in memory +allocated with @code{scm_gc_malloc}, looking for live pointers. This +means that if @code{scm_gc_malloc}-allocated memory contains a pointer +to some other part of the memory, the garbage collector notices it and +prevents it from being reclaimed@footnote{In Guile up to 1.8, memory +allocated with @code{scm_gc_malloc} was @emph{not} visited by the +collector in the mark phase. Consequently, the GC had to be told +explicitly about pointers to live objects contained in the memory block, +e.g., @i{via} SMOB mark functions (@pxref{Smobs, +@code{scm_set_smob_mark}})}. Conversely, memory allocated with +@code{scm_gc_malloc_pointerless} is assumed to be ``pointer-less'' and +is not scanned for pointers. For memory that is not associated with a Scheme object, you can use @code{scm_malloc} instead of @code{malloc}. Like @@ -193,9 +197,11 @@ Allocate @var{size} bytes of automatically-managed memory. The memory is automatically freed when no longer referenced from any live memory block. -Memory allocated with @code{scm_gc_malloc} or @code{scm_gc_calloc} is -scanned for pointers. Memory allocated by -@code{scm_gc_malloc_pointerless} is not scanned. +When garbage collection occurs, Guile will visit the words in memory +allocated with @code{scm_gc_malloc} or @code{scm_gc_calloc}, looking for +pointers to other memory allocations that are managed by the GC. In +contrast, memory allocated by @code{scm_gc_malloc_pointerless} is not +scanned for pointers. The @code{scm_gc_realloc} call preserves the ``pointerlessness'' of the memory area pointed to by @var{mem}. Note that you need to pass the old diff --git a/doc/ref/libguile-concepts.texi b/doc/ref/libguile-concepts.texi index 9785f4d..e93d987 100644 --- a/doc/ref/libguile-concepts.texi +++ b/doc/ref/libguile-concepts.texi @@ -203,22 +203,38 @@ set'' of garbage collection; any value on the heap that is referenced directly or indirectly by a member of the root set is preserved, and all other objects are eligible for reclamation. -The Scheme stack and heap are scanned precisely; that is to say, Guile -knows about all inter-object pointers on the Scheme stack and heap. -This is not the case, unfortunately, for pointers on the C stack and -static data segment. For this reason we have to scan the C stack and -static data segment @dfn{conservatively}; any value that looks like a -pointer to a GC-managed object is treated as such, whether it actually -is a reference or not. Thus, scanning the C stack and static data -segment is guaranteed to find all actual references, but it might also -find words that only accidentally look like references. These ``false -positives'' might keep @code{SCM} objects alive that would otherwise be -considered dead. While this might waste memory, keeping an object -around longer than it strictly needs to is harmless. This is why this -technique is called ``conservative garbage collection''. In practice, -the wasted memory seems to be no problem, as the static C root set is -almost always finite and small, given that the Scheme stack is separate -from the C stack. +In Guile, garbage collection has two logical phases: the @dfn{mark +phase}, in which the collector discovers the set of all live objects, +and the @dfn{sweep phase}, in which the collector reclaims the resources +associated with dead objects. The mark phase pauses the program and +traces all @code{SCM} object references, starting with the root set. +The sweep phase actually runs concurrently with the main program, +incrementally reclaiming memory as needed by allocation. + +In the mark phase, the garbage collector traces the Scheme stack and +heap @dfn{precisely}. Because the Scheme stack and heap are managed by +Guile, Guile can know precisely where in those data structures it might +find references to other heap objects. This is not the case, +unfortunately, for pointers on the C stack and static data segment. +Instead of requiring the user to inform Guile about all variables in C +that might point to heap objects, Guile traces the C stack and static +data segment @dfn{conservatively}. That is to say, Guile just treats +every word on the C stack and every C global variable as a potential +reference in to the Scheme heap@footnote{Note that Guile does not scan +the C heap for references, so a reference to a @code{SCM} object from a +memory segment allocated with @code{malloc} will have to use some other +means to keep the @code{SCM} object alive. @xref{Garbage Collection +Functions}.}. Any value that looks like a pointer to a GC-managed +object is treated as such, whether it actually is a reference or not. +Thus, scanning the C stack and static data segment is guaranteed to find +all actual references, but it might also find words that only +accidentally look like references. These ``false positives'' might keep +@code{SCM} objects alive that would otherwise be considered dead. While +this might waste memory, keeping an object around longer than it +strictly needs to is harmless. This is why this technique is called +``conservative garbage collection''. In practice, the wasted memory +seems to be no problem, as the static C root set is almost always finite +and small, given that the Scheme stack is separate from the C stack. The stack of every thread is scanned in this way and the registers of the CPU and all other memory locations where local variables or function -- 2.8.3 --=-=-=--