1# Reference (template)
2
3Holds a counted reference to a [`Napi::Value`](value.md) object; initially a weak reference unless otherwise specified, may be changed to/from a strong reference by adjusting the refcount.
4
5The referenced `Napi::Value` is not immediately destroyed when the reference count is zero; it is merely then eligible for garbage-collection if there are no other references to the `Napi::Value`.
6
7`Napi::Reference` objects allocated in static space, such as a global static instance, must call the `SuppressDestruct` method to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. Avoid using this if at all possible.
8
9The following classes inherit, either directly or indirectly, from `Napi::Reference`:
10
11* [`Napi::ObjectWrap`](object_wrap.md)
12* [`Napi::ObjectReference`](object_reference.md)
13* [`Napi::FunctionReference`](function_reference.md)
14
15## Methods
16
17### Factory Method
18
19```cpp
20static Napi::Reference<T> Napi::Reference::New(const T& value, uint32_t initialRefcount = 0);
21```
22
23* `[in] value`: The value which is to be referenced.
24
25* `[in] initialRefcount`: The initial reference count.
26
27### Empty Constructor
28
29```cpp
30Napi::Reference::Reference();
31```
32
33Creates a new _empty_ `Napi::Reference` instance.
34
35### Constructor
36
37```cpp
38Napi::Reference::Reference(napi_env env, napi_value value);
39```
40
41* `[in] env`: The `napi_env` environment in which to construct the `Napi::Reference` object.
42
43* `[in] value`: The Node-API primitive value to be held by the `Napi::Reference`.
44
45### Env
46
47```cpp
48Napi::Env Napi::Reference::Env() const;
49```
50
51Returns the `Napi::Env` value in which the `Napi::Reference` was instantiated.
52
53### IsEmpty
54
55```cpp
56bool Napi::Reference::IsEmpty() const;
57```
58
59Determines whether the value held by the `Napi::Reference` is empty.
60
61### Value
62
63```cpp
64T Napi::Reference::Value() const;
65```
66
67Returns the value held by the `Napi::Reference`.
68
69### Ref
70
71```cpp
72uint32_t Napi::Reference::Ref() const;
73```
74
75Increments the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the increment fails.
76
77### Unref
78
79```cpp
80uint32_t Napi::Reference::Unref() const;
81```
82
83Decrements the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the decrement fails.
84
85### Reset (Empty)
86
87```cpp
88void Napi::Reference::Reset();
89```
90
91Sets the value held by the `Napi::Reference` to be empty.
92
93### Reset
94
95```cpp
96void Napi::Reference::Reset(const T& value, uint32_t refcount = 0);
97```
98
99* `[in] value`: The value which is to be referenced.
100
101* `[in] initialRefcount`: The initial reference count.
102
103Sets the value held by the `Napi::Reference`.
104
105### SuppressDestruct
106
107```cpp
108void Napi::Reference::SuppressDestruct();
109```
110
111Call this method on a `Napi::Reference` that is declared as static data to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid.
112
113 Avoid using this if at all possible. If you do need to use static data, **MAKE SURE** to warn your users that your addon is **NOT** threadsafe.
114