Add module documentation. Fix #248

This commit is contained in:
Eugen Wissner 2017-06-24 09:08:19 +02:00
parent ede0107fd7
commit 47b394d8c3
7 changed files with 70 additions and 55 deletions

View File

@ -3,6 +3,8 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/** /**
* This module contains buffers designed for C-style input/output APIs.
*
* Copyright: Eugene Wissner 2016-2017. * Copyright: Eugene Wissner 2016-2017.
* License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/, * License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/,
* Mozilla Public License, v. 2.0). * Mozilla Public License, v. 2.0).

View File

@ -3,6 +3,8 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/** /**
* This package provides mathematical functions.
*
* Copyright: Eugene Wissner 2016-2017. * Copyright: Eugene Wissner 2016-2017.
* License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/, * License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/,
* Mozilla Public License, v. 2.0). * Mozilla Public License, v. 2.0).

View File

@ -3,6 +3,11 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/** /**
* This module contains the interface for implementing custom allocators.
*
* Allocators are classes encapsulating memory allocation strategy. This allows
* to decouple memory management from the algorithms and the data.
*
* Copyright: Eugene Wissner 2016-2017. * Copyright: Eugene Wissner 2016-2017.
* License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/, * License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/,
* Mozilla Public License, v. 2.0). * Mozilla Public License, v. 2.0).

View File

@ -3,6 +3,8 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/** /**
* Allocator based on $(D_PSYMBOL malloc), $(D_PSYMBOL realloc) and $(D_PSYMBOL free).
*
* Copyright: Eugene Wissner 2017. * Copyright: Eugene Wissner 2017.
* License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/, * License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/,
* Mozilla Public License, v. 2.0). * Mozilla Public License, v. 2.0).
@ -14,7 +16,8 @@ import core.stdc.stdlib;
import tanya.memory.allocator; import tanya.memory.allocator;
/** /**
* Wrapper for malloc/realloc/free from the C standard library. * Wrapper for $(D_PSYMBOL malloc)/$(D_PSYMBOL realloc)/$(D_PSYMBOL free) from
* the C standard library.
*/ */
final class Mallocator : Allocator final class Mallocator : Allocator
{ {

View File

@ -3,6 +3,8 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/** /**
* Native allocator for Posix and Windows.
*
* Copyright: Eugene Wissner 2016-2017. * Copyright: Eugene Wissner 2016-2017.
* License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/, * License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/,
* Mozilla Public License, v. 2.0). * Mozilla Public License, v. 2.0).

View File

@ -3,6 +3,8 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/** /**
* Dynamic memory management.
*
* Copyright: Eugene Wissner 2016-2017. * Copyright: Eugene Wissner 2016-2017.
* License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/, * License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/,
* Mozilla Public License, v. 2.0). * Mozilla Public License, v. 2.0).

View File

@ -5,6 +5,9 @@
/** /**
* Smart pointers. * Smart pointers.
* *
* A smart pointer is an object that wraps a raw pointer or a reference
* (class, array) to manage its lifetime.
*
* Copyright: Eugene Wissner 2016-2017. * Copyright: Eugene Wissner 2016-2017.
* License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/, * License: $(LINK2 https://www.mozilla.org/en-US/MPL/2.0/,
* Mozilla Public License, v. 2.0). * Mozilla Public License, v. 2.0).
@ -41,7 +44,7 @@ package final class RefCountedStore(T)
if (op == "--" || op == "++") if (op == "--" || op == "++")
in in
{ {
assert(counter > 0); assert(this.counter > 0);
} }
body body
{ {
@ -63,15 +66,6 @@ package final class RefCountedStore(T)
return 0; return 0;
} }
} }
private unittest
{
auto rcs = defaultAllocator.make!(RefCountedStore!int);
assert(rcs >= 1);
assert(rcs > 0);
assert(!(rcs > 2));
defaultAllocator.dispose(rcs);
}
} }
package void separateDeleter(T)(RefCountedStore!T storage, package void separateDeleter(T)(RefCountedStore!T storage,
@ -107,8 +101,8 @@ struct RefCounted(T)
invariant invariant
{ {
assert(storage is null || allocator_ !is null); assert(this.storage is null || this.allocator_ !is null);
assert(storage is null || deleter !is null); assert(this.storage is null || this.deleter !is null);
} }
/** /**
@ -122,18 +116,13 @@ struct RefCounted(T)
* *
* Precondition: $(D_INLINECODE allocator !is null) * Precondition: $(D_INLINECODE allocator !is null)
*/ */
this()(auto ref Payload!T value, this(Payload!T value, shared Allocator allocator = defaultAllocator)
shared Allocator allocator = defaultAllocator)
{ {
this(allocator); this(allocator);
this.storage = allocator.make!Storage(); this.storage = allocator.make!Storage();
this.deleter = &separateDeleter!(Payload!T); this.deleter = &separateDeleter!(Payload!T);
move(value, this.storage.payload); this.storage.payload = value;
static if (__traits(isRef, value))
{
value = null;
}
} }
/// Ditto. /// Ditto.
@ -165,7 +154,7 @@ struct RefCounted(T)
*/ */
~this() ~this()
{ {
if (this.storage !is null && !(this.storage.counter && --this.storage)) if (this.storage !is null && !(this.storage > 0 && --this.storage))
{ {
deleter(this.storage, allocator); deleter(this.storage, allocator);
} }
@ -218,22 +207,6 @@ struct RefCounted(T)
assert(*rc == 7); assert(*rc == 7);
} }
private @nogc unittest
{
auto rc = defaultAllocator.refCounted!int(5);
void func(RefCounted!int param) @nogc
{
assert(rc.count == 2);
rc = defaultAllocator.make!int(7);
assert(rc.count == 1);
assert(*rc == 7);
}
func(rc);
assert(rc.count == 1);
assert(*rc == 7);
}
/// Ditto. /// Ditto.
ref typeof(this) opAssign(typeof(null)) ref typeof(this) opAssign(typeof(null))
{ {
@ -254,7 +227,7 @@ struct RefCounted(T)
return this; return this;
} }
private unittest private @nogc unittest
{ {
RefCounted!int rc; RefCounted!int rc;
assert(!rc.isInitialized); assert(!rc.isInitialized);
@ -349,6 +322,37 @@ unittest
assert(*rc.storage.payload == 9); assert(*rc.storage.payload == 9);
} }
private @nogc unittest
{
auto rc = defaultAllocator.refCounted!int(5);
void func(RefCounted!int param) @nogc
{
assert(param.count == 2);
param = defaultAllocator.make!int(7);
assert(param.count == 1);
assert(*param == 7);
}
func(rc);
assert(rc.count == 1);
assert(*rc == 5);
}
private @nogc unittest
{
RefCounted!int rc;
void func(RefCounted!int param) @nogc
{
assert(param.count == 0);
param = defaultAllocator.make!int(7);
assert(param.count == 1);
assert(*param == 7);
}
func(rc);
assert(rc.count == 0);
}
private unittest private unittest
{ {
RefCounted!int rc1, rc2; RefCounted!int rc1, rc2;
@ -603,8 +607,6 @@ private @nogc unittest
auto p1 = defaultAllocator.make!int(5); auto p1 = defaultAllocator.make!int(5);
auto p2 = p1; auto p2 = p1;
auto rc = RefCounted!int(p1, defaultAllocator); auto rc = RefCounted!int(p1, defaultAllocator);
assert(p1 is null);
assert(rc.get() is p2); assert(rc.get() is p2);
} }
@ -651,16 +653,10 @@ struct Unique(T)
* *
* Precondition: $(D_INLINECODE allocator !is null) * Precondition: $(D_INLINECODE allocator !is null)
*/ */
this()(auto ref Payload!T value, this(Payload!T value, shared Allocator allocator = defaultAllocator)
shared Allocator allocator = defaultAllocator)
{ {
this(allocator); this(allocator);
this.payload = value;
move(value, this.payload);
static if (__traits(isRef, value))
{
value = null;
}
} }
/// Ditto. /// Ditto.
@ -683,12 +679,9 @@ struct Unique(T)
* Destroys the owned object. * Destroys the owned object.
*/ */
~this() ~this()
{
if (this.payload !is null)
{ {
allocator.dispose(this.payload); allocator.dispose(this.payload);
} }
}
/** /**
* Initialized this $(D_PARAM Unique) and takes ownership over * Initialized this $(D_PARAM Unique) and takes ownership over
@ -728,6 +721,14 @@ struct Unique(T)
return this; return this;
} }
///
@nogc unittest
{
auto rc = defaultAllocator.unique!int(5);
rc = defaultAllocator.make!int(7);
assert(*rc == 7);
}
/** /**
* Returns: Reference to the owned object. * Returns: Reference to the owned object.
*/ */
@ -806,7 +807,6 @@ struct Unique(T)
{ {
auto p = defaultAllocator.make!int(5); auto p = defaultAllocator.make!int(5);
auto s = Unique!int(p, defaultAllocator); auto s = Unique!int(p, defaultAllocator);
assert(p is null);
assert(*s == 5); assert(*s == 5);
} }
@ -912,9 +912,8 @@ private @nogc unittest
{ {
auto p1 = defaultAllocator.make!int(5); auto p1 = defaultAllocator.make!int(5);
auto p2 = p1; auto p2 = p1;
auto rc = Unique!int(p1, defaultAllocator);
assert(p1 is null); auto rc = Unique!int(p1, defaultAllocator);
assert(rc.get() is p2); assert(rc.get() is p2);
} }