Replace NXhandle* with NXhandle& (#39425)

### Description of work

#### Summary of work
`napi` was apparently written before pass-by-reference was a thing. Or
at least it did not make proper use of pass-by-reference, instead
passing `void**` objects to enable edited the `void*` in certain
methods.

This replaces the four methods in `napi` and `napi5` that use `void**`
to instead use `void*&`.

Refs #38332 

#### Further detail of work

Using pass-by-reference means the `void*` object can be directly
modified, without having to use dereferencing. This impacted the
internals of the methods.

The few places in the code that call these methods were also changed,
including in the `napi` tests.

### To test:

This is a minor refactor that should not change behavior. If NeXus files
can still be opened, closed, reopened, and flushed (which the existing
unit tests prove) then everything is fine.

*This does not require release notes* because it is way under the hood,
away from users.

---

### Reviewer

Please comment on the points listed below ([full
description](http://developer.mantidproject.org/ReviewingAPullRequest.html)).
**Your comments will be used as part of the gatekeeper process, so
please comment clearly on what you have checked during your review.** If
changes are made to the PR during the review process then your final
comment will be the most important for gatekeepers. In this comment you
should make it clear why any earlier review is still valid, or confirm
that all requested changes have been addressed.

#### Code Review

- Is the code of an acceptable quality?
- Does the code conform to the [coding
standards](http://developer.mantidproject.org/Standards/)?
- Are the unit tests small and test the class in isolation?
- If there is GUI work does it follow the [GUI
standards](http://developer.mantidproject.org/Standards/GUIStandards.html)?
- If there are changes in the release notes then do they describe the
changes appropriately?
- Do the release notes conform to the [release notes
guide](https://developer.mantidproject.org/Standards/ReleaseNotesGuide.html)?

#### Functional Tests

- Do changes function as described? Add comments below that describe the
tests performed?
- Do the changes handle unexpected situations, e.g. bad input?
- Has the relevant (user and developer) documentation been
added/updated?

Does everything look good? Mark the review as **Approve**. A member of
`@mantidproject/gatekeepers` will take care of it.

### Gatekeeper

If you need to request changes to a PR then please add a comment and set
the review status to "Request changes". This will stop the PR from
showing up in the list for other gatekeepers.

Author: rboston628

Framework/Nexus/inc/MantidNexus/napi.h

@@ -150,14 +150,14 @@ extern "C" {
  * \return NX_OK on success, NX_ERROR in the case of an error.
  * \ingroup c_init
  */
-MANTID_NEXUS_DLL NXstatus NXopen(CONSTCHAR *filename, NXaccess access_method, NXhandle *pHandle);
+MANTID_NEXUS_DLL NXstatus NXopen(CONSTCHAR *filename, NXaccess access_method, NXhandle &handle);
 
 /**
  * Opens an existing NeXus file a second time for e.g. access from another thread.
  * \return NX_OK on success, NX_ERROR in the case of an error.
  * \ingroup c_init
  */
-MANTID_NEXUS_DLL NXstatus NXreopen(NXhandle pOrigHandle, NXhandle *pNewHandle);
+MANTID_NEXUS_DLL NXstatus NXreopen(NXhandle pOrigHandle, NXhandle &pNewHandle);
 
 /**
  * close a NeXus file
@@ -166,15 +166,15 @@ MANTID_NEXUS_DLL NXstatus NXreopen(NXhandle pOrigHandle, NXhandle *pNewHandle);
  * \return NX_OK on success, NX_ERROR in the case of an error.
  * \ingroup c_init
  */
-MANTID_NEXUS_DLL NXstatus NXclose(NXhandle *pHandle);
+MANTID_NEXUS_DLL NXstatus NXclose(NXhandle &handle);
 
 /**
  * flush data to disk
  * \param pHandle A NeXus file handle as initialized by NXopen.
  * \return NX_OK on success, NX_ERROR in the case of an error.
  * \ingroup c_readwrite
  */
-MANTID_NEXUS_DLL NXstatus NXflush(NXhandle *pHandle);
+MANTID_NEXUS_DLL NXstatus NXflush(NXhandle &handle);
 
 /**
  * NeXus groups are NeXus way of structuring information into a hierarchy.

Framework/Nexus/inc/MantidNexus/napi5.h

@@ -9,11 +9,11 @@
 
 /* HDF5 interface */
 
-extern NXstatus NX5open(CONSTCHAR *filename, NXaccess access_method, NXhandle *pHandle);
-extern NXstatus NX5reopen(NXhandle pOrigHandle, NXhandle *pNewHandle);
+extern NXstatus NX5open(CONSTCHAR *filename, NXaccess access_method, NXhandle &handle);
+extern NXstatus NX5reopen(NXhandle origHandle, NXhandle &newHandle);
 
-extern NXstatus NX5close(NXhandle *pHandle);
-extern NXstatus NX5flush(NXhandle *pHandle);
+extern NXstatus NX5close(NXhandle &handle);
+extern NXstatus NX5flush(NXhandle &handle);
 
 extern NXstatus NX5makegroup(NXhandle handle, CONSTCHAR *name, CONSTCHAR *NXclass);
 extern NXstatus NX5opengroup(NXhandle handle, CONSTCHAR *name, CONSTCHAR *NXclass);

Framework/Nexus/inc/MantidNexus/napi_internal.h

@@ -33,9 +33,9 @@
 
 typedef struct {
   NXhandle pNexusData;
-  NXstatus (*nxreopen)(NXhandle pOrigHandle, NXhandle *pNewHandle);
-  NXstatus (*nxclose)(NXhandle *pHandle);
-  NXstatus (*nxflush)(NXhandle *pHandle);
+  NXstatus (*nxreopen)(NXhandle origHandle, NXhandle &newHandle);
+  NXstatus (*nxclose)(NXhandle &handle);
+  NXstatus (*nxflush)(NXhandle &handle);
   NXstatus (*nxmakegroup)(NXhandle handle, CONSTCHAR *name, CONSTCHAR *NXclass);
   NXstatus (*nxopengroup)(NXhandle handle, CONSTCHAR *name, CONSTCHAR *NXclass);
   NXstatus (*nxclosegroup)(NXhandle handle);

Framework/Nexus/src/NexusFile.cpp

@@ -105,7 +105,7 @@ void File::initOpenFile(const string &filename, const NXaccess access) {
   }
 
   NXhandle temp;
-  NXstatus status = NXopen(filename.c_str(), access, &(temp));
+  NXstatus status = NXopen(filename.c_str(), access, temp);
   if (status != NXstatus::NX_OK) {
     stringstream msg;
     msg << "NXopen(" << filename << ", " << access << ") failed";
@@ -145,7 +145,7 @@ File &File::operator=(File const &f) {
 
 File::~File() {
   if (m_close_handle && m_pfile_id != NULL) {
-    NXstatus status = NXclose(&(*this->m_pfile_id));
+    NXstatus status = NXclose(*m_pfile_id);
     this->m_pfile_id = NULL;
     if (status != NXstatus::NX_OK) {
       stringstream msg;
@@ -157,12 +157,12 @@ File::~File() {
 
 void File::close() {
   if (this->m_pfile_id != NULL) {
-    NAPI_CALL(NXclose(&(*this->m_pfile_id)), "NXclose failed");
+    NAPI_CALL(NXclose(*m_pfile_id), "NXclose failed");
     this->m_pfile_id = NULL;
   }
 }
 
-void File::flush() { NAPI_CALL(NXflush(&(*this->m_pfile_id)), "NXflush failed"); }
+void File::flush() { NAPI_CALL(NXflush(*m_pfile_id), "NXflush failed"); }
 
 //------------------------------------------------------------------------------------------------------------------
 // FILE NAVIGATION METHODS

Framework/Nexus/src/napi.cpp

@@ -98,19 +98,19 @@ static pNexusFunction handleToNexusFunc(NXhandle fid) {
 /*--------------------------------------------------------------------*/
 static NXstatus NXinternalopen(CONSTCHAR *userfilename, NXaccess am, pFileStack fileStack);
 /*----------------------------------------------------------------------*/
-NXstatus NXopen(CONSTCHAR *userfilename, NXaccess am, NXhandle *gHandle) {
+NXstatus NXopen(CONSTCHAR *userfilename, NXaccess am, NXhandle &gHandle) {
   NXstatus status;
   pFileStack fileStack = NULL;
 
-  *gHandle = NULL;
+  gHandle = NULL;
   fileStack = makeFileStack();
   if (fileStack == NULL) {
     NXReportError("ERROR: no memory to create filestack");
     return NXstatus::NX_ERROR;
   }
   status = NXinternalopen(userfilename, am, fileStack);
   if (status == NXstatus::NX_OK) {
-    *gHandle = fileStack;
+    gHandle = fileStack;
   }
 
   return status;
@@ -148,7 +148,7 @@ static NXstatus NXinternalopen(CONSTCHAR *userfilename, NXaccess am, pFileStack
   }
 
   NXhandle hdf5_handle = NULL;
-  NXstatus retstat = NX5open(userfilename, am, &hdf5_handle);
+  NXstatus retstat = NX5open(userfilename, am, hdf5_handle);
   if (retstat != NXstatus::NX_OK) {
     free(fHandle);
   } else {
@@ -161,11 +161,11 @@ static NXstatus NXinternalopen(CONSTCHAR *userfilename, NXaccess am, pFileStack
   return retstat;
 }
 
-NXstatus NXreopen(NXhandle pOrigHandle, NXhandle *pNewHandle) {
+NXstatus NXreopen(NXhandle pOrigHandle, NXhandle &newHandle) {
   pFileStack newFileStack;
   pFileStack origFileStack = static_cast<pFileStack>(pOrigHandle);
   pNexusFunction fOrigHandle = NULL, fNewHandle = NULL;
-  *pNewHandle = NULL;
+  newHandle = NULL;
   newFileStack = makeFileStack();
   if (newFileStack == NULL) {
     NXReportError("ERROR: no memory to create filestack");
@@ -184,32 +184,32 @@ NXstatus NXreopen(NXhandle pOrigHandle, NXhandle *pNewHandle) {
   }
   fNewHandle = static_cast<NexusFunction *>(malloc(sizeof(NexusFunction)));
   memcpy(fNewHandle, fOrigHandle, sizeof(NexusFunction));
-  fNewHandle->nxreopen(fOrigHandle->pNexusData, &(fNewHandle->pNexusData));
+  fNewHandle->nxreopen(fOrigHandle->pNexusData, fNewHandle->pNexusData);
   pushFileStack(newFileStack, fNewHandle, peekFilenameOnStack(origFileStack));
-  *pNewHandle = newFileStack;
+  newHandle = newFileStack;
   return NXstatus::NX_OK;
 }
 
 /* ------------------------------------------------------------------------- */
 
-NXstatus NXclose(NXhandle *fid) {
+NXstatus NXclose(NXhandle &fid) {
   NXhandle hfil;
   NXstatus status;
   pFileStack fileStack = NULL;
   pNexusFunction pFunc = NULL;
-  if (*fid == NULL) {
+  if (fid == NULL) {
     return NXstatus::NX_OK;
   }
-  fileStack = (pFileStack)*fid;
+  fileStack = static_cast<pFileStack>(fid);
   pFunc = peekFileOnStack(fileStack);
   hfil = pFunc->pNexusData;
-  status = pFunc->nxclose(&hfil);
+  status = pFunc->nxclose(hfil);
   pFunc->pNexusData = hfil;
   free(pFunc);
   popFileStack(fileStack);
   if (fileStackDepth(fileStack) < 0) {
     killFileStack(fileStack);
-    *fid = NULL;
+    fid = NULL;
   }
   /* we can't set fid to NULL always as the handle points to a stack of files for external file support */
   /*
@@ -264,7 +264,7 @@ NXstatus NXclosegroup(NXhandle fid) {
     NXgetgroupID(fid, &currentID);
     peekIDOnStack(fileStack, &closeID);
     if (NXsameID(fid, &closeID, &currentID) == NXstatus::NX_OK) {
-      NXclose(&fid);
+      NXclose(fid);
       status = NXclosegroup(fid);
     } else {
       status = pFunc->nxclosegroup(pFunc->pNexusData);
@@ -330,7 +330,7 @@ NXstatus NXclosedata(NXhandle fid) {
     NXgetdataID(fid, &currentID);
     peekIDOnStack(fileStack, &closeID);
     if (NXsameID(fid, &closeID, &currentID) == NXstatus::NX_OK) {
-      NXclose(&fid);
+      NXclose(fid);
       status = NXclosedata(fid);
     } else {
       status = pFunc->nxclosedata(pFunc->pNexusData);
@@ -420,16 +420,16 @@ NXstatus NXopensourcegroup(NXhandle fid) {
 
 /*----------------------------------------------------------------------*/
 
-NXstatus NXflush(NXhandle *pHandle) {
+NXstatus NXflush(NXhandle &handle) {
   NXhandle hfil;
   pFileStack fileStack = NULL;
   NXstatus status;
 
   pNexusFunction pFunc = NULL;
-  fileStack = (pFileStack)*pHandle;
+  fileStack = static_cast<pFileStack>(handle);
   pFunc = peekFileOnStack(fileStack);
   hfil = pFunc->pNexusData;
-  status = pFunc->nxflush(&hfil);
+  status = pFunc->nxflush(hfil);
   pFunc->pNexusData = hfil;
   return status;
 }

Framework/Nexus/src/napi5.cpp

@@ -207,10 +207,10 @@ static void buildCurrentAddress(pNexusFile5 self, char *addressBuffer, // cppche
 
    --------------------------------------------------------------------- */
 
-NXstatus NX5reopen(NXhandle pOrigHandle, NXhandle *pNewHandle) {
+NXstatus NX5reopen(NXhandle origHandle, NXhandle &newHandle) {
   pNexusFile5 pNew = NULL, pOrig = NULL;
-  *pNewHandle = NULL;
-  pOrig = static_cast<pNexusFile5>(pOrigHandle);
+  newHandle = NULL;
+  pOrig = static_cast<pNexusFile5>(origHandle);
   pNew = static_cast<pNexusFile5>(malloc(sizeof(NexusFile5)));
   if (!pNew) {
     NXReportError("ERROR: no memory to create File datastructure");
@@ -226,7 +226,7 @@ NXstatus NX5reopen(NXhandle pOrigHandle, NXhandle *pNewHandle) {
   strcpy(pNew->iAccess, pOrig->iAccess);
   pNew->iNXID = NX5SIGNATURE;
   pNew->iStack5[0].iVref = 0; /* root! */
-  *pNewHandle = static_cast<NXhandle>(pNew);
+  newHandle = static_cast<NXhandle>(pNew);
   return NXstatus::NX_OK;
 }
 
@@ -300,7 +300,7 @@ herr_t set_str_attribute(hid_t parent_id, CONSTCHAR *name, CONSTCHAR *buffer) {
   return 0;
 }
 
-NXstatus NX5open(CONSTCHAR *filename, NXaccess am, NXhandle *pHandle) {
+NXstatus NX5open(CONSTCHAR *filename, NXaccess am, NXhandle &handle) {
   hid_t root_id;
   pNexusFile5 pNew = NULL;
   char pBuffer[512];
@@ -309,7 +309,7 @@ NXstatus NX5open(CONSTCHAR *filename, NXaccess am, NXhandle *pHandle) {
   unsigned int vers_major, vers_minor, vers_release, am1;
   hid_t fapl = -1;
 
-  *pHandle = NULL;
+  handle = NULL;
 
   if (H5get_libversion(&vers_major, &vers_minor, &vers_release) < 0) {
     NXReportError("ERROR: cannot determine HDF5 library version");
@@ -422,17 +422,17 @@ NXstatus NX5open(CONSTCHAR *filename, NXaccess am, NXhandle *pHandle) {
   }
   pNew->iNXID = NX5SIGNATURE;
   pNew->iStack5[0].iVref = 0; /* root! */
-  *pHandle = static_cast<NXhandle>(pNew);
+  handle = static_cast<NXhandle>(pNew);
   return NXstatus::NX_OK;
 }
 
 /* ------------------------------------------------------------------------- */
 
-NXstatus NX5close(NXhandle *fid) {
+NXstatus NX5close(NXhandle &fid) {
   pNexusFile5 pFile = NULL;
   herr_t iRet;
 
-  pFile = NXI5assert(*fid);
+  pFile = NXI5assert(fid);
 
   iRet = 0;
   /*
@@ -467,7 +467,7 @@ NXstatus NX5close(NXhandle *fid) {
     free(pFile->iCurrentLD);
   }
   free(pFile);
-  *fid = NULL;
+  fid = NULL;
   H5garbage_collect();
   return NXstatus::NX_OK;
 }
@@ -1327,11 +1327,11 @@ NXstatus NX5makelink(NXhandle fid, NXlink *sLink) {
 
 /*----------------------------------------------------------------------*/
 
-NXstatus NX5flush(NXhandle *pHandle) {
+NXstatus NX5flush(NXhandle &handle) {
   pNexusFile5 pFile = NULL;
   herr_t iRet;
 
-  pFile = NXI5assert(*pHandle);
+  pFile = NXI5assert(handle);
   if (pFile->iCurrentD != 0) {
     iRet = H5Fflush(pFile->iCurrentD, H5F_SCOPE_LOCAL);
   } else if (pFile->iCurrentG != 0) {

Framework/Nexus/test/leak_test1.cpp

@@ -16,20 +16,20 @@ int main() {
   NXhandle fileid;
 
   removeFile(szFile); // in case it was left over from previous run
-  if (NXopen(szFile.c_str(), access_mode, &fileid) != NXstatus::NX_OK)
+  if (NXopen(szFile.c_str(), access_mode, fileid) != NXstatus::NX_OK)
     ON_ERROR("NXopen failed!\n")
 
-  if (NXclose(&fileid) != NXstatus::NX_OK)
+  if (NXclose(fileid) != NXstatus::NX_OK)
     ON_ERROR("NXclose failed!\n")
 
   for (iReOpen = 0; iReOpen < nReOpen; iReOpen++) {
     if (0 == iReOpen % 100)
       printf("loop count %d\n", iReOpen);
 
-    if (NXopen(szFile.c_str(), NXACC_RDWR, &fileid) != NXstatus::NX_OK)
+    if (NXopen(szFile.c_str(), NXACC_RDWR, fileid) != NXstatus::NX_OK)
       ON_ERROR("NXopen failed!\n");
 
-    if (NXclose(&fileid) != NXstatus::NX_OK)
+    if (NXclose(fileid) != NXstatus::NX_OK)
       ON_ERROR("NXclose failed!\n");
   }
 

Framework/Nexus/test/leak_test2.cpp

@@ -26,7 +26,7 @@ int main() {
     remove(strFile);
     printf("file %s\n", strFile);
     NXhandle fileid;
-    if (NXopen(strFile, access_mode, &fileid) != NXstatus::NX_OK) {
+    if (NXopen(strFile, access_mode, fileid) != NXstatus::NX_OK) {
       std::cerr << "NXopen failed!" << std::endl;
       return 1;
     }
@@ -94,7 +94,7 @@ int main() {
       }
     }
 
-    if (NXclose(&fileid) != NXstatus::NX_OK) {
+    if (NXclose(fileid) != NXstatus::NX_OK) {
       std::cerr << "NXclose failed!" << std::endl;
       return 1;
     }

Framework/Nexus/test/leak_test3.cpp

@@ -37,7 +37,7 @@ int main() {
 
     NXhandle fileid;
     NXlink aLink;
-    if (NXopen(szFile, NXACC_CREATE5, &fileid) != NXstatus::NX_OK)
+    if (NXopen(szFile, NXACC_CREATE5, fileid) != NXstatus::NX_OK)
       ON_ERROR("NXopen_failed")
 
     for (iEntry = 0; iEntry < nEntry; iEntry++) {
@@ -87,7 +87,7 @@ int main() {
         ON_ERROR("NXclosegroup failed!")
     }
 
-    if (NXclose(&fileid) != NXstatus::NX_OK)
+    if (NXclose(fileid) != NXstatus::NX_OK)
       ON_ERROR("NXclose failed!")
 
     // Delete file