[m-rev.] for review: Add support for weak pointers to the C RTS

[Julien Fischer]

On Tue, 15 Apr 2014, Paul Bone wrote:

> For review by anyone.
>
> Branches: master, version-14.01-branch
>
> ---
>
> Add support for weak pointers to the C RTS
>
> A weak pointer (aka weak reference) is a pointer to some garbage collector
> (GC) allocated object or memory that is not considered by the GC when
> deciding if the object is garbage or not.  Additionally, if the object is
> reclaimed by the GC the GC will zero-out this pointer so that other code can
> test if this object is still available.  Weak pointer can be useful when
> implementing caches or cyclic data structures (my motivation for this
> change).
>
> This change introduces a weak pointer type (a typedef) in Mercury's runtime
> system for the C backends.  Two macros are provided to create and deference
> these weak pointers.  Extra documentation, and constraints on how these can
> be used are described in mercury_memory.h.
>
> runtime/mercury_memory.c:
> runtime/mercury_memory.h:
>    As above.
>
> tests/general/weak_ptr.m:
> tests/general/Mmakefile:
>    Add a test for the C RTS's weak pointer support
>
> tests/general/weak_ptr.exp:
>    Expected output for the test.  This isn't the real program's output.
>    weak_ptr's output is too volatile to use reliably (see weak_ptr.m).
> ---
> runtime/mercury_memory.c   |  19 +++++-
> runtime/mercury_memory.h   |  85 ++++++++++++++++++++++-
> tests/general/Mmakefile    |  11 ++-
> tests/general/weak_ptr.exp |   1 +
> tests/general/weak_ptr.m   | 163 +++++++++++++++++++++++++++++++++++++++++++++
> 5 files changed, 276 insertions(+), 3 deletions(-)
> create mode 100644 tests/general/weak_ptr.exp
> create mode 100644 tests/general/weak_ptr.m
>
> diff --git a/runtime/mercury_memory.c b/runtime/mercury_memory.c
> index 8251696..76769cf 100644
> --- a/runtime/mercury_memory.c
> +++ b/runtime/mercury_memory.c
> @@ -2,7 +2,7 @@
> ** vim: ts=4 sw=4 expandtab
> */
> /*
> -** Copyright (C) 1994-2000,2002-2004, 2006, 2008, 2011 The University of Melbourne.
> +** Copyright (C) 1994-2000,2002-2004, 2006, 2008, 2011, 2014 The University of Melbourne.
> ** This file may only be copied under the terms of the GNU Library General
> ** Public License - see the file COPYING.LIB in the Mercury distribution.
> */
> @@ -381,6 +381,23 @@ MR_GC_realloc(void *old_ptr, size_t num_bytes)
>     return ptr;
> }
>
> +#ifdef MR_BOEHM_GC
> +void*
> +MR_weak_ptr_read_unsafe(void* weak_ptr_) {
> +    MR_weak_ptr *weak_ptr = weak_ptr_;
> +
> +    /*
> +    ** Even though we check for NULL in the macro we must re-check here
> +    ** while holding the GC's allocation lock.
> +    */
> +    if (MR_NULL_WEAK_PTR != *weak_ptr) {
> +        return GC_REVEAL_POINTER(*weak_ptr);
> +    } else {
> +        return NULL;
> +    }
> +}
> +#endif

Add /* MR_BOEHM_GC */ there.

...

> void *
> diff --git a/runtime/mercury_memory.h b/runtime/mercury_memory.h
> index bc1c1ed..862d1fa 100644
> --- a/runtime/mercury_memory.h
> +++ b/runtime/mercury_memory.h
> @@ -1,5 +1,5 @@
> /*
> -** Copyright (C) 1994-2000,2002, 2004, 2006, 2008 The University of Melbourne.
> +** Copyright (C) 1994-2000,2002, 2004, 2006, 2008, 2014 The University of Melbourne.
> ** This file may only be copied under the terms of the GNU Library General
> ** Public License - see the file COPYING.LIB in the Mercury distribution.
> */
> @@ -175,6 +175,18 @@ extern	void 	MR_ensure_big_enough_buffer(char **buffer_ptr,
> **      XXX this interface is subject to change.
> **
> ** Note: consider using the _attrib variants below.
> +**
> +** MR_new_weak_ptr(ptr, object):
> +**  Create a weak pointer to object and store it in the memory pointed to by
> +**  ptr (a double pointer).  object must have been allocated using one of
> +**  the MR_GC methods.  Weak pointers only work with the Boehm collector
> +**  (.gc grades).  In other grades this is an ordinary pointer.
> +**
> +** MR_weak_ptr_read(weak_ptr):
> +**  Dereference a weak pointer.  Returns NULL of the pointed to object has
> +**  been deallocated.  If weak_ptr is NULL then NULL is returned, so the
> +**  programmer doesn't need to do an extra NULL check incase their pointer
> +**  is deliberatly NULL;
> */

I suggest:

      Dereference a weak pointer.  Returns NULL if the object being
      pointed to has been deallocated or if weak_ptr is NULL.

and delete the last bit.  Also the indentation of these macro
descriptions is not consistent with the indentation directly above them.

Cheers,
Julien.