coding/patterns/memory.md

@@ -98,6 +98,39 @@ using the null-constructed form (which is defined to be noexcept).
 return tmp<vectorField>(new vectorField(0));
 ```
 
+
+### Handling of references or local storage
+
+\since 2012, partly earlier
+
+Both tmp and refPtr (a refernce and/or pointer) containers serve a
+similar purpose - to hold a reference or an allocated pointer to
+memory. The principal difference is that tmp has intrusive
+ref-counting and a number of OpenFOAM operations are built around it.
+Whereas refPtr has no ref-counting, which makes it suitable for
+holding any type of object.
+
+Both tmp and refPtr can hold a const or modifiable reference or an
+allocated pointer. This especially makes refPtr ideal for storage and
+addressing.  For example,
+
+```
+tmp<volScalarField> tfld(nullptr);
+auto* ptr = getObjectPtr<volScalarField>("field");
+if (ptr)
+{
+    // using a writable reference
+    tfld.ref(*ptr);
+}
+else
+{
+    // using an allocated pointer
+    tfld.reset(volScalarField::New(...));
+}
+auto& fld = tfld.ref();
+```
+
+
 ----
 
 Copyright (C) 2019-2020 OpenCFD Ltd.