[phobos] [D-Programming-Language/phobos] f6994e: Improve std.typecons.Unique

Fri Apr 24 11:24:20 PDT 2015

  Branch: refs/heads/master
  Home:   https://github.com/D-Programming-Language/phobos
  Commit: f6994ea02f4aa102c13a434d44f4f06aeffaa8f7
      https://github.com/D-Programming-Language/phobos/commit/f6994ea02f4aa102c13a434d44f4f06aeffaa8f7
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-02 (Thu, 02 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Improve std.typecons.Unique

Whenever D is brought up to the general programming public,
the garbage collector is quickly raised as a point of contention.
Regardless of how legitimate or well-informed these concerns are,
it would be a massive public relations boon --- and great for the language,
to boot --- if we could trot out a solid said of RAII-based smart pointers
for those who prefer to use them. We have a solid start in
std.typecons.Unique and std.typecons.RefCounted.
Unfortunately, these classes seem to be victims of bit rot and
compiler bugs of days long gone.

An overview of the changes in this commit is as follows:

- Unique's underlying data now uses malloc and free
  instead of the garbage collector. Given that many people use RAII
  smart pointers to escape the GC, it seems to make more sense to
  avoid it here. On a related note, isn't delete deprecated?
  The current destructor uses it.

- std.algorithm.move is used instead of a special release
  member function. Whether by design or by happy accident,
  move transfers ownership between Unique pointers in a very
  similar manner to C++'s std::move with std::unique_ptr.
  Along with being a familiar paradigm to C++ users,
  using move to transfer ownership makes more intuitive sense
  and builds consistency with the rest of Phobos.

- With std.algorithm.move transferring ownership, release now just
  frees the underlying pointer and nulls the Unique.

- Unique.create is no longer compiled out using version(None).
  Regardless of whether or not there is language support for
  checking uniqueness, a utility function that creates a Unique,
  taking the same arguments as the underlying type's constructor,
  is extremely useful, as demonstrated by the addition of
  make_unique to C++14.

- Because Unique.create is now in place and Unique is backed with
  malloc, constructors taking a pointer have been removed.
  This encourages the use of create as the idiomatic,
  consistent method to, well, create Unique objects.
  If one can only get a Unique by calling create or moving another
  into it, we also ensures uniqueness in one fell swoop.

- A new method, get, returns the underlying pointer, for use in
  functions and code that do not play a role in the life cycle
  of the object. Smart pointers are as much about ownership
  semantics as they are about allocating and freeing memory,
  and non-owning code should continue to refer to data using a raw
  pointer or a reference.

  Commit: db544d55d5e949cd4b58e2ca1b636a2269842ad2
      https://github.com/D-Programming-Language/phobos/commit/db544d55d5e949cd4b58e2ca1b636a2269842ad2
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-03 (Fri, 03 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Issue onOutOfMemoryError on bad malloc in Unique

  Commit: a5150a043bc4f3c5e47c51ba042b4f457b23e859
      https://github.com/D-Programming-Language/phobos/commit/a5150a043bc4f3c5e47c51ba042b4f457b23e859
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-03 (Fri, 03 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Fix outOfMemoryError import

  Commit: 6d42be9fdd9d41f621befe7a44e12f28ae061d41
      https://github.com/D-Programming-Language/phobos/commit/6d42be9fdd9d41f621befe7a44e12f28ae061d41
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-03 (Fri, 03 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Use class version of std.conv.emplace for Unique

I picked up the trick of converting a pointer into an array
using the [0 .. size] syntax from std/regex/package.d.

Unique.create is still segfaulting, but this seems to be an issue
with the class version of emplace regardless of this Unique work.
The bug can be found here:
https://issues.dlang.org/show_bug.cgi?id=14402

  Commit: b3c94c26d137a93f8f09e1edf8d483e530f0ae72
      https://github.com/D-Programming-Language/phobos/commit/b3c94c26d137a93f8f09e1edf8d483e530f0ae72
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-05 (Sun, 05 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Make Unique use the GC again

It is currently impossible (or so it seems) to use malloc and
emplace to create a nested class or struct, so we'll return to
using the GC for now. We'll also restore the constructors that take
a RefT, as using new _inside_ the context of the nested class or
struct is apparently the only way to create one currently.

  Commit: dba6bd5464eb57807832e49589a2fb50cb27cd38
      https://github.com/D-Programming-Language/phobos/commit/dba6bd5464eb57807832e49589a2fb50cb27cd38
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-06 (Mon, 06 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Revamp and cleanup of Unique

>From the related pull request
(https://github.com/D-Programming-Language/phobos/pull/3139),
there seems to be a general consensus that it is more important to
do Unique "right", even if that means breaking changes, so long as
there is a clean migration path. With that in mind, I have made the
following additional changes:

- Instead of constructors that take a RefT, Uniques can now be
  created one of two ways: via .create or .fromNested.
  See the DDocs of both for details.

- opDot is replaced with "alias _p this". A cursorty Google search
  indicates that opDot is deprecated and that alias this is the
  preferred method. Like C++'s unique_ptr, Unique now enjoys
  pointer-like operations (such as dereferencing),
  but cannot be set to null or assigned from a different pointer
  due to opAssign and the disabled postblit constructor.

- Consequently, isEmpty has been removed. Instead, just use
  is null as you would with a pointer.

- Removal of redundant unit tests

- Various comment and unit test cleanup

  Commit: c5605bf2c8cd75ba755c13f9b73393305c571a66
      https://github.com/D-Programming-Language/phobos/commit/c5605bf2c8cd75ba755c13f9b73393305c571a66
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-13 (Mon, 13 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Turn Unique.create into a freestanding unique()

Also cleaned up the Unique documentation a bit.
Unfortunately some of the unittests could not be used as documented
unittests because placing them in the struct gives an error about
RTInfo!(Nested) being recursvely expanded.

  Commit: e112ec9b7f8bd621239433bf9a644ccb19d230fa
      https://github.com/D-Programming-Language/phobos/commit/e112ec9b7f8bd621239433bf9a644ccb19d230fa
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-16 (Thu, 16 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Return Unique to malloc/free

Marking its various bits as @nogc is still proving to be a challenge
since Object.destroy is not @nogc, among other things.

We _are_ using GC.addRange and GC.removeRange to handle anything
inside the underlying type that uses GC.
Why the user would do this in conjunction with Unique is
questionable, but until we can explicitly forbid doing so, let's
not break garbage collection for them.

Note that this also makes nested structs and classes impossible,
because there is no way AFAIK to get the frame pointer into
unique()

  Commit: 836c55197e423d34295185fa1c2dcade9202cad7
      https://github.com/D-Programming-Language/phobos/commit/836c55197e423d34295185fa1c2dcade9202cad7
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-17 (Fri, 17 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Do not let Unique escape underlying references

See https://github.com/D-Programming-Language/phobos/pull/3139#discussion-diff-28203345

  Commit: d24b738cccf7e6ec09025e33e9732b59eaab76ab
      https://github.com/D-Programming-Language/phobos/commit/d24b738cccf7e6ec09025e33e9732b59eaab76ab
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-17 (Fri, 17 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Clean up Unique alias this

  Commit: d2289a4d4190357b31755b9f122be4cb5a5cc5e0
      https://github.com/D-Programming-Language/phobos/commit/d2289a4d4190357b31755b9f122be4cb5a5cc5e0
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-19 (Sun, 19 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Return Unique.release to original form, deprecate it

  Commit: 1cc0b487897a26bfae2115ad31ead3c8eece339f
      https://github.com/D-Programming-Language/phobos/commit/1cc0b487897a26bfae2115ad31ead3c8eece339f
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-21 (Tue, 21 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Use emplace to set up structs for Unique

  Commit: 1204e04e1e06acae8c6f1d1f2d55c7fd433bfc79
      https://github.com/D-Programming-Language/phobos/commit/1204e04e1e06acae8c6f1d1f2d55c7fd433bfc79
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-21 (Tue, 21 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Unique for classes returns the object pointer

  Commit: 5a34389f39193907583b450c34e5d50ac168edaf
      https://github.com/D-Programming-Language/phobos/commit/5a34389f39193907583b450c34e5d50ac168edaf
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-21 (Tue, 21 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Fix typo in Unique.create

  Commit: ad3784f3b3d03b24e5b658f62fc81b42e558fe19
      https://github.com/D-Programming-Language/phobos/commit/ad3784f3b3d03b24e5b658f62fc81b42e558fe19
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-24 (Fri, 24 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Cleanup of Unique as per Martin Nowak's suggestions

See https://github.com/D-Programming-Language/phobos/pull/3139

  Commit: 5054c6f689233aef479e7e6cc7a47207161b656a
      https://github.com/D-Programming-Language/phobos/commit/5054c6f689233aef479e7e6cc7a47207161b656a
  Author: Matt Kline <matt at bitbashing.io>
  Date:   2015-04-24 (Fri, 24 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Elaborate on nested types and Unique

They don't go well together.

  Commit: 8f4a85bc83d0205f053b80cafc87b65ad8032ec7
      https://github.com/D-Programming-Language/phobos/commit/8f4a85bc83d0205f053b80cafc87b65ad8032ec7
  Author: Martin Nowak <code at dawg.eu>
  Date:   2015-04-24 (Fri, 24 Apr 2015)

  Changed paths:
    M std/typecons.d

  Log Message:
  -----------
  Merge pull request #3139 from mrkline/better-unique

Improve std.typecons.Unique

Compare: https://github.com/D-Programming-Language/phobos/compare/d74e4d787a44...8f4a85bc83d0