Skip to content

Commit 0683003

Browse files
committed
Improved the documentation
1 parent f243e06 commit 0683003

1 file changed

Lines changed: 17 additions & 1 deletion

File tree

README.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,12 @@ It provides two methods:
88
- `object.Defer` to defer closing the resources created by the current object (for example `foo.Defer(foo.db.Close)`).
99
- `object.Close`, once called, executes all of the deferred operations and returns errors if necessary.
1010

11-
Additionally, `ex.Terminate` helps you to find leaks by reporting errors if an object gets garbage-collected without having been closed.
11+
Additionally, `ex.Terminate` helps you find leaks by reporting errors if an object gets garbage-collected without having been closed.
12+
13+
`ex.Terminator` has several benefits over maintaining your own `Close` methods:
14+
- Similarly to the `defer` keyword, it is easier to keep track of what is being closed or not, because both the open and close operations always goes together. Meanwhile, it is very easy to forget about it when writing or maintaining a `Close` method.
15+
- Errors in manually maintained `Close` methods are often ignored, and handling it explicitly makes the readability worse. `ex.Terminator` takes care of that for you, and includes helpful error messages.
16+
- `ex.Terminator` takes care of closing the resources in the right order, which is easy to get wrong when manually done.
1217

1318
## Example
1419

@@ -96,6 +101,17 @@ func main() {
96101
}
97102
```
98103

104+
## Is this based on `runtime.SetFinalizer`?
105+
106+
No. Resources are closed synchronously, meaning that the `Close` methods still must be called, either via `defer`, `.Defer` or manually.
107+
108+
However, `ex.Terminator` uses `runtime.SetFinalizer` to help the developers find mistakes: an error message is printed in the console whenever a non-Closed object gets garbage-collected.
109+
But this only used for this purpose. Closing the objects is never done in `SetFinalizer`.
110+
111+
## Can I use it outside the constructor?
112+
113+
Yes! Although I only provided examples using the constructor (because it is the most common use case), you can use `.Defer` in any method and any time of the life-cycle of your objects.
114+
99115
## In which order are resources closed?
100116

101117
`ex.Terminator` follows the same convention than the `defer` keyword: the last deferred operation is executed first:

0 commit comments

Comments
 (0)