added new experimental API isUniqueRef (#21812)

* added new experimental API isUniqueRef

* typo

1 files changed, 12 insertions, 0 deletions

diff --git a/lib/system/arc.nim b/lib/system/arc.nim
index 2186806d6..b264cbedd 100644
--- a/lib/system/arc.nim
+++ b/lib/system/arc.nim
@@ -113,6 +113,18 @@ proc nimNewObjUninit(size, alignment: int): pointer {.compilerRtl.} =
 proc nimDecWeakRef(p: pointer) {.compilerRtl, inl.} =
   decrement head(p)
 
+proc isUniqueRef*[T](x: ref T): bool {.inline.} =
+  ## Returns true if the object `x` points to is uniquely referenced. Such
+  ## an object can potentially be passed over to a different thread safely,
+  ## if great care is taken. This queries the internal reference count of
+  ## the object which is subject to lots of optimizations! In other words
+  ## the value of `isUniqueRef` can depend on the used compiler version and
+  ## optimizer setting.
+  ## Nevertheless it can be used as a very valuable debugging tool and can
+  ## be used to specify the constraints of a threading related API
+  ## via `assert isUniqueRef(x)`.
+  head(cast[pointer](x)).rc == 0
+
 proc nimIncRef(p: pointer) {.compilerRtl, inl.} =
   when defined(nimArcDebug):
     if head(p).refId == traceId: