forked from openrs2/openrs2
parent
d801e5fda6
commit
c3d7e9d081
@ -0,0 +1,47 @@ |
|||||||
|
# Reference counting |
||||||
|
|
||||||
|
[Netty][netty] uses reference counting for some objects, such as `ByteBuf`s. |
||||||
|
The Netty documentation explains its |
||||||
|
[use of reference counting][netty-ref-counting] in more detail. |
||||||
|
|
||||||
|
OpenRS2 has an extension method that automatically wraps a block of code in a |
||||||
|
`try`/`finally` block, calling `release()` in the `finally` block. It is very |
||||||
|
similar to Kotlin's extension method for `close()`ing `Closeable`s (and in fact |
||||||
|
has the same name: `use`). |
||||||
|
|
||||||
|
A typical pattern for allocating and then releasing a `ByteBuf` using this |
||||||
|
method is: |
||||||
|
|
||||||
|
```kt |
||||||
|
alloc.buffer().use { buf -> |
||||||
|
// use buf here |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
In OpenRS2, a method that consumes a `ByteBuf` is generally not responsible for |
||||||
|
releasing it - the caller is. This provides more flexibility, as the caller |
||||||
|
might want to continue reading from the buffer. (For example, after calling |
||||||
|
`Js5Compression.uncompress()`, the caller will probably want to read the 2 byte |
||||||
|
version trailer from the same buffer.) |
||||||
|
|
||||||
|
For obvious reasons, a method that produces a `ByteBuf` is generally not |
||||||
|
responsible for releasing it - again, the caller is. However, arranging for the |
||||||
|
`ByteBuf` to be freed if an exception occurs between the `ByteBuf` being |
||||||
|
allocated and returned is tricky. The following pattern is useful for correctly |
||||||
|
releasing/retaining the buffer depending on whether an exception occurs or not: |
||||||
|
|
||||||
|
```kt |
||||||
|
alloc.buffer().use { buf -> |
||||||
|
// write to buf here |
||||||
|
return buf.retain() |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
If any of the code prior to the `return` fails, the buffer is released. |
||||||
|
|
||||||
|
If the `return` is reached, no more exceptions can occur. The reference count |
||||||
|
is increased to counteract the `finally` block decreasing it, such that by the |
||||||
|
time the buffer reaches the caller its reference count is 1. |
||||||
|
|
||||||
|
[netty]: https://netty.io/ |
||||||
|
[netty-ref-counting]: https://netty.io/wiki/reference-counted-objects.html |
Loading…
Reference in new issue