From 752f586c01960f550e92baf1016065264ef2823a Mon Sep 17 00:00:00 2001 From: Stephane Poirier <stephane-poirier@synchrotron-soleil.fr> Date: Wed, 1 Feb 2023 11:37:48 +0100 Subject: [PATCH] Documentation update --- .gitignore | 1 + README | 29 + doc/Doxyfile | 2 +- include/nexuscpp/nexuscpp.h | 45 +- include/nexuscpp/nxbuffer.h | 317 +++++----- include/nexuscpp/nxfile.h | 1035 ++++++++++++++++---------------- include/nexuscpp/nxfinalizer.h | 74 ++- include/nexuscpp/nxwriter.h | 449 +++++++++----- licence.txt | 165 +++++ src/nxhdf5.cpp | 2 +- src/nxwriter.cpp | 1 + 11 files changed, 1288 insertions(+), 832 deletions(-) create mode 100644 README create mode 100644 licence.txt diff --git a/.gitignore b/.gitignore index 3e15e11..69f7c3e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /.vscode/ +html/ *.bin *.dll *.simu diff --git a/README b/README new file mode 100644 index 0000000..cefe5b0 --- /dev/null +++ b/README @@ -0,0 +1,29 @@ +------------------------------------------------------------------------------ +// NeXusCPP LIBRARY +------------------------------------------------------------------------------ + + Copyright (C) 2005-2023 - S. Poirier, C. Rodrigez, J. Berthaud, N.Leclercq + + NeXusCPP is a C++ NeXus files and datasets manipulation library + It is built on top of the HDF5 library. + + The NeXusCPP library is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 2 of the License, or (at + your option) any later version. + + The YAT4Tango library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General + Public License for more details. + + A copy of the GPL version 3 is available below. + + The reference documentation is available here : https://www2.synchrotron-soleil.fr/controle/docs/nexuscpp/nexuscpp_html/ + + Please read the ReleaseNotes.txt file to known about recent changes + + Contact: + Stephane POIRIER (stephane.poirier@synchrotron-soleil.fr) + Synchrotron SOLEIL +------------------------------------------------------------------------------ diff --git a/doc/Doxyfile b/doc/Doxyfile index 594b20c..d59dcd6 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -38,7 +38,7 @@ PROJECT_NAME = NexusCPP # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 3.2.2 +PROJECT_NUMBER = 3.5.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/include/nexuscpp/nexuscpp.h b/include/nexuscpp/nexuscpp.h index ae227d9..2be0586 100644 --- a/include/nexuscpp/nexuscpp.h +++ b/include/nexuscpp/nexuscpp.h @@ -1,16 +1,16 @@ //***************************************************************************** /// Synchrotron SOLEIL /// -/// NeXus C++ API over NAPI +/// NeXus C++ API /// -/// Creation : 2010/07/18 -/// Author : Stephane Poirier +/// Creation : 16/02/2005 +/// Authors : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud /// /// This program is free software; you can redistribute it and/or modify it under /// the terms of the GNU General Public License as published by the Free Software /// Foundation; version 2 of the License. -/// -/// This program is distributed in the hope that it will be useful, but WITHOUT +/// +/// This program is distributed in the hope that it will be useful, but WITHOUT /// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS /// FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. /// @@ -19,6 +19,41 @@ #ifndef __NX_CPP_H__ #define __NX_CPP_H__ +// ---------------------------------------------------------------------------- +//! \mainpage NeXusCPP library +//! \tableofcontents +//! NeXusCPP is a C++ NeXus files and datasets library.\n +//! It is built on top of the HDF5 library.\n +//! Its purpose is to provide the developer with useful, easy to use and +//! powerful C++ tools for creating/reading/writing NeXus files.\n +//! The topics currently addressed by NeXusCPP library are: +//! - \subpage lowlevelPage "Low level API" +//! - \subpage highlevelPage "High level API" +//! - \subpage streamingPage "Streaming API" +//! +//! <b>Main Author & Maintainer:</b>\n +//! - Stephane Poirier - Synchrotron SOLEIL - France\n +//! +//! <b>NeXusCPP license:</b> +//! +//! Copyright (C) 2006-2021 The Tango Community (http://tango-controls.org) +//! +//! The NeXusCPP library is free software; you can redistribute it and/or modify it +//! under the terms of the GNU General Public License as published by the Free +//! Software Foundation; either version 2 of the License, or (at your option) +//! any later version. +//! +//! The NeXusCPP library is distributed in the hope that it will be useful, +//! but WITHOUT ANY WARRANTY; without even the implied warranty of +//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General +//! Public License for more details. +//! +//! See COPYING file for license details +//! +//! <b>Main Contact:</b>\n +//! Stephane Poirier - Synchrotron SOLEIL - France +// ---------------------------------------------------------------------------- + // standard library objets #include <iostream> #include <vector> diff --git a/include/nexuscpp/nxbuffer.h b/include/nexuscpp/nxbuffer.h index b9bbb97..643987a 100644 --- a/include/nexuscpp/nxbuffer.h +++ b/include/nexuscpp/nxbuffer.h @@ -1,10 +1,10 @@ //***************************************************************************** /// Synchrotron SOLEIL /// -/// Nexus API for Tango servers +/// Nexus C++ API /// -/// Creation : 2011/01/12 -/// Authors : Stephane Poirier, Clement Rodriguez +/// Creation : 16/02/2005 +/// Authors : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud /// /// This program is free software; you can redistribute it and/or modify it under /// the terms of the GNU General Public License as published by the Free Software @@ -19,6 +19,23 @@ #ifndef __NX_BUFFER_H__ #define __NX_BUFFER_H__ +// ============================================================================ +//! \page streamingPage streaming NeXus API documentation +//! \tableofcontents +//! +//! \section secC1 Streaming NeXus API +//! The Streaming API provide an object classe that allow to write continuous +//! data without knowing final datasets sizes and shapes +//! +//! \section secC2 Streaming NeXus API classes +//! Links to classes : \n +//! - nxcpp::DataStreamer +//! - nxcpp::NexusDataStreamerFinalizer +//! - nxcpp::OverwriteError +//! +// ============================================================================ + + // including standard files #ifndef __STRING_INCLUDED__ #include <string> @@ -93,10 +110,10 @@ private: */ //============================================================================= -/// OverwriteError -/// -/// This class may be used by the DataStreamer in case of -/// a buffer file already exists before the acquisition start +//! OverwriteError +//! +//! This class may be used by the DataStreamer in case of +//! a buffer file already exists before the acquisition start //============================================================================= class NEXUSCPP_DECL OverwriteError: public NexusException { @@ -111,7 +128,7 @@ public: }; //============================================================================== -/// DataItemCategory +//! DataItemCategory ///============================================================================== enum DataItemCategory { @@ -128,33 +145,30 @@ enum DataItemCategory #define NX_ATTR_SLAB_STOP "buf_stop" #define NX_ATTR_ACQ_BATCH "buf_batch" -/// type of buffered data -/// '0' for one shoot data (scalar, spectrum or image), '1' for data subset in a 1D acquisition, ... +// type of buffered data +// '0' for one shoot data (scalar, spectrum or image), '1' for data subset in a 1D acquisition, ... #define NX_ATTR_DATA_DIM "buf_dim" //============================================================================== -/// Write notification +//! Write notification //============================================================================== struct WriteNotification { - /// data item name + //! data item name std::string item_name; - /// The number of written items + //! The number of written items yat::uint32 write_count; }; -// Write notification callback +//! Write notification callback YAT_DEFINE_CALLBACK(WriteNotificationCallback, WriteNotification); //============================================================================== -/// DataStreamer -/// -/// This class aims to ease the writing process of local NeXus files. -/// -///@notice BufferedData is no longer instantiable because this class name -/// is now deprecated +//! DataStreamer +//! +//! This is a utility classe aimed to allow streaming data into NeXus files //============================================================================== class NEXUSCPP_DECL DataStreamer: public DatasetWriter::IFlushNotification, public NexusFileWriter::INotify, @@ -163,12 +177,21 @@ class NEXUSCPP_DECL DataStreamer: public DatasetWriter::IFlushNotification, { public: + //! Memory mode typedef enum NEXUSCPP_DECL MemoryMode { - COPY = 0, // Default mode for all data items - NO_COPY // Applicable only for 2D data items (images) + //! Using COPY mode (default), data is internally copied so + //! input data buffer can be reused§deallocated immmadiately after pushing + //! data + COPY = 0, + + //! NO_COPY allow faster streaming but you can't deallocate or reuse pushed + //! data buffer immediately, you have to be sure the data was properly written + //! (you can use a WriteNotificationCallBack in that purpose) + NO_COPY } MemoryMode; + //! Write statistices typedef struct NEXUSCPP_DECL Statistics { Statistics(); @@ -183,61 +206,63 @@ public: float fAverageMbPerSec; } Statistics; + //! DataStreamer configuration structure typedef struct NEXUSCPP_DECL Config { - /// buffer file names suffix + //! buffer file names suffix yat::String buffer_name; - /// total number of data (may be either scalars, spectrums or images) + //! total number of data (may be either scalars, spectrums or images) std::size_t acquisition_size; - /// number of data to be stored into one buffer file + //! number of data to be stored into one buffer file std::size_t buffer_size; - /// Target directory for streamed data + //! Target directory for streamed data yat::String target_path; - /// Data source root name. data file will ba named using this name followed - /// by a index number + //! Data source root name. data file will ba named using this name followed + //! by a index number yat::String data_source; - /// The optional write notification callback + //! The optional write notification callback WriteNotificationCallback write_notif_cb; - /// SYNCHRONOUS OR ASYNCHRONOUS writing mode + //! SYNCHRONOUS OR ASYNCHRONOUS writing mode NexusFileWriter::WriteMode write_mode; - /// Compresssion filter options + //! Compresssion filter options FilterConfig filter_config; - /// Compression filer + //! Compression filer CompressionFilter compress_filter; - /// Minimum uncompressed byte size of data item that will be compressed + //! Minimum uncompressed byte size of data item that will be compressed std::size_t min_bytes_for_compression; - /// The data source device name + //! The data source device name yat::String device_name; - /// Messages logging handler + //! Messages logging handler IMessageHandler* message_handler_p; - /// Throw an exception if destination buffer file already exists ? + //! Throw an exception if destination buffer file already exists ? bool throw_if_file_exists; // ---------------- // error management // ---------------- - /// optional exception handler + //! optional exception handler IExceptionHandler* exception_handler_p; - /// max attempts on write access in case of error + //! max attempts on write access in case of error std::size_t max_attempts; - /// delay between each try in ms + //! delay between each try in ms std::size_t retry_delay; + //! c-tor Config() { acquisition_size = 0; @@ -253,139 +278,161 @@ public: } } Config; - /// Constructor + //! Constructor + //! + //! \param cfg Configuration DataStreamer(const Config& cfg); - /// Destructors + //! Destructor virtual ~DataStreamer(); - /// Initialization - /// @param config Config struct + // Initialization + //## Should be a private method... void Initialize(const Config& cfg); - /// Tell the streamer we start a new acquisition sequence, therefore the first file index of every stream - /// will be reset to '1' - /// This method whould not be called for all subsequent DataStreamer objects - /// + //! Tell the streamer we start a new acquisition sequence, therefore the first file index of every stream + //! will be reset to '1' + //! This method whould not be called for all subsequent DataStreamer objects static void ResetBufferIndex(); - /// Set the write notification callback - /// Each tile a - /// + //! Set the write notification callback + //! + //! \param cb WritenotificationCallBack method void SetWriteNotificationCallback(const WriteNotificationCallback& cb); //@{ Data items declarations - /// Generic data item declaration - /// + //! Generic data item declaration + //! + //! Use this method to declare a new item for which you ha ve to stream data + //! + //! \param sItemName item name + //! \param viDimSize Dimensions array of the canonical data + //! \param bDataSignal If 'true' this item will ba marked as 'signal' in + //! the Nexus files stream void AddDataItem(const std::string &sItemName, const std::vector<int>& viDimSize, bool bDataSignal=true) ; - /// scalar data item - /// + //! Add a Scalar-type data item + //! + //! \param sItemName item name + //! \param bDataSignal If 'true' this item will ba marked as 'signal' in void AddDataItem0D(const std::string &sItemName, bool bDataSignal=true) ; - /// 1-d (spectrum) dataitem - /// - void AddDataItem1D(const std::string &sItemName, int iSizeDim, bool bDataSignal=true) - ; - - /// 2-d (image) dataitem - /// + //! Add a 1-D (spectrum) data item + //! + //! \param sItemName item name + //! \param iSizeDim size of the data item + //! \param bDataSignal If 'true' this item will ba marked as 'signal' in + void AddDataItem1D(const std::string &sItemName, int iSizeDim, bool bDataSignal=true); + + //! Add a 2-D (image) data item + //! + //! \param sItemName item name + //! \param iSizeDim1 size of the 1st data item dimension + //! \param iSizeDim2 size of the 2nd data item dimension + //! \param bDataSignal If 'true' this item will ba marked as 'signal' in void AddDataItem2D(const std::string &sItemName, int iSizeDim1, int iSizeDim2, bool bDataSignal=true) ; - /// axis data item (equals to 1-d data item but with additionnal attributes) - /// + //! Add a axis-type data item + //! + //! This type of data item is similar to 1-D data item but with additional + //! dataset attributes + //! + //! \param sItemName item name + //! \param iDimension related scan dimension for this axis (first is '1') + //! \param iOrder axis order on the dimension void AddDataAxis(const std::string &sItemName, int iDimension, int iOrder) ; - /// Set dataitem memory management mode + //! Set dataitem memory management mode + //! + //! \param sItemName item name + //! \param mode Writing mode (COPY/NO_COPY) void SetDataItemMemoryMode(const std::string &sItemName, MemoryMode mode); //@} //@{ Writing datas and attributes - /// PushData - /// - /// @param sItemName sensor's name to which data will be added - /// @param tData Added data - /// @param vtDetectPos sensor's data position in the acquisition multidimensional space - /// @param nCount canonical data count - /// + //! PushData + //! + //! \param sItemName sensor's name to which data will be added + //! \param tData Added data + //! \param nCount canonical data count template <class TYPE> void PushData(const std::string &sItemName, const TYPE *tData, unsigned int nCount=1); - /// PushAxisData - /// - /// @param sName Axis name on which datas will be added - /// @param viVecPos Axis value's position in the acquisition multidimensional space - /// @param pValue Measured position on the axis - /// + //! PushAxisData + //! + //! \param sName Axis name on which datas will be added + //! \param TValue Measured position on the axis template <class TYPE> void PushAxisData(const std::string &sName, TYPE TValue); - /// PushIntegerAttribute - /// Set an integer-type attribute belonging to the date item named sItemName. - /// - /// @param sItemName name of the dataitem or axis which the attribute will belong to - /// @param sName name of the attribute - /// @param lValue value of the attribute + //! PushIntegerAttribute + //! Set an integer-type attribute belonging to the date item named sItemName. + //! + //! \param sItemName name of the dataitem or axis which the attribute will belong to + //! \param sName name of the attribute + //! \param lValue value of the attribute /// void PushIntegerAttribute(const std::string &sItemName, const std::string &sName, long lValue); - /// PushFloatAttribute - /// Set an integer-type attribute belonging to the date item named sItemName. - /// - /// @param sItemName name of the dataitem or axis which the attribute will belong to - /// @param sName name of the attribute - /// @param lValue value of the attribute - /// + //! PushFloatAttribute + //! Set an integer-type attribute belonging to the date item named sItemName. + //! + //! \param sItemName name of the dataitem or axis which the attribute will belong to + //! \param sName name of the attribute + //! \param dValue value of the attribute void PushFloatAttribute(const std::string &sItemName, const std::string &sName, double dValue); - /// PushStringAttribute - /// Set an std::string-type attribute belonging to the date item named sItemName. - /// - /// @param sItemName name of the dataitem or axis which the attribute will belong to - /// @param sName name of the attribute - /// @param strValue value of the attribute - /// + //! PushStringAttribute + //! Set an std::string-type attribute belonging to the date item named sItemName. + //! + //! \param sItemName name of the dataitem or axis which the attribute will belong to + //! \param sName name of the attribute + //! \param strValue value of the attribute void PushStringAttribute(const std::string &sItemName, const std::string &sName, const std::string &strValue) ; //@} - /// Set exception handler - /// + //! Set exception handler + //! + //! \param pHandler The exception handler void SetExceptionHandler(IExceptionHandler *pHandler); - /// Set message handler - /// + //! Set message handler + //! + //! \param pHandler The message handler void SetMessageHandler(IMessageHandler *pHandler); - /// Sets the name of the tango device + //! Sets the name of the tango device + //! + //§ \param strDevice Device name void SetDeviceName(const std::string &strDevice) { m_cfg.device_name = strDevice; } - /// Reset buffer in order to start a new acquisition + //! Reset buffer in order to start a new acquisition void Reset(); - /// Terminate the buffering process + //! Terminate the buffering process void Finalize(); - /// Abort the bufferization process - /// - /// @param bSynchronize if true wait for last pushed data to be recorder - /// + //! Abort the bufferization process + //! + //! \param bSynchronize if true wait for last pushed data to be recorder void Abort(bool bSynchronize=false); - /// Close the buffer and wait for synchronization + //! Close the buffer and wait for synchronization void Stop(); - /// Ask if all data have been flushed + //! Ask if all data have been flushed bool IsDone(); - /// Wait the recording of all pushed data + //! Wait the recording of all pushed data void Synchronize(); //@{ Setters + //## deprecated methods void SetWriteMode(const NexusFileWriter::WriteMode &mode) { m_cfg.write_mode = mode; } void SetTargetFolder(const std::string &sPath) { m_cfg.target_path = sPath; } //@} @@ -396,47 +443,43 @@ public: int GetNbPushInFile() const { return m_cfg.buffer_size; } //@} - /// Clean - /// Clean all buffers from destination folder - /// @warning Don't use this method if you are in a multiple acquisition system - /// (i.e: 1 acquisition for the whole system == n acquisition at device level) - /// + //! Clean + //! Clean all buffers from destination folder + //! \warning Don't use this method if you are in a multiple acquisition system + //! (i.e: 1 acquisition for the whole system == n acquisition at device level) void Clean(); - /// IFlushNotification - /// + //! IFlushNotification void OnFlushData(DatasetWriter* pWriter); - /// Check if a data item has been declared - /// + //! Check if a data item has been declared bool IsExistingItem(const std::string &sItemName); - // Exception handler + //! Get exception handler IExceptionHandler* ExceptionHandler() const{ return m_pExceptHandler; } - /// Message handler + //! Get message handler IMessageHandler* MessageHandler() const{ return m_pMsgHandler; } //@{ Statistics - /// Reset all statistics + //! Reset all statistics void ResetStatistics(); - /// Gets a copy of the statistics + //! Gets a copy of the statistics Statistics GetStatistics() const; //@} //@{ Static methods - /// GenerateBufferName - /// Generate a standard buffer file's name according to the base - /// name and given indexes - /// - /// @param strPrefix prefix used to ensure uniqueness of file name - /// @param sBaseName buffer file base name - /// @param iIndex buffer file index - /// + //! GenerateBufferName + //! Generate a standard buffer file's name according to the base + //! name and given indexes + //! + //! \param sBaseName buffer file base name + //! \param lIndex buffer file index + //! \param strPrefix prefix used to ensure uniqueness of file name static std::string GenerateBufferName(const std::string &sBaseName, long lIndex, const std::string &strPrefix=""); @@ -500,16 +543,16 @@ private: // PrivPushData // - // @param sItemInfo sensor's information data - // @param tData Added data - // @param vtDetectPos sensor's data position in the acquisition multidimensional space - // @param nCount canonical data count + // sItemInfo sensor's information data + // tData Added data + // vtDetectPos sensor's data position in the acquisition multidimensional space + // nCount canonical data count // void PrivPushDataItems(DataItemInfo &sItemInfo, const void *pData, std::size_t nCount, bool bNoCopy); // Push pending data // - // @param sItemInfo sensor's information data + // sItemInfo sensor's information data // void PushPendingData(DataItemInfo& ItemInfo); diff --git a/include/nexuscpp/nxfile.h b/include/nexuscpp/nxfile.h index d97f739..c58e481 100644 --- a/include/nexuscpp/nxfile.h +++ b/include/nexuscpp/nxfile.h @@ -1,7 +1,7 @@ //***************************************************************************** /// Synchrotron SOLEIL /// -/// NeXus C++ API over NAPI +/// NeXus C++ API /// /// Creation : 16/02/2005 /// Author : Stephane Poirier @@ -19,6 +19,25 @@ #ifndef __NX_FILE_H__ #define __NX_FILE_H__ +// ============================================================================ +//! \page lowlevelPage NeXus API documentation +//! \tableofcontents +//! +//! \section secA1 Low-level NeXus API classes +//! The NeXus API implement generic classes in order to read and write NeXus data. +//! +//! \section secA2 NeXus API classes +//! Links to NeXusAPI classes : \n +//! - nxcpp::NexusFile +//! - nxcpp::NexusDataSet +//! - nxcpp::NexusDataSetInfo +//! - nxcpp::NexusAttr +//! - nxcpp::NexusAttrInfo +//! - nxcpp::NexusItemInfo +//! - nxcpp::NexusItemID +//! +// ============================================================================ + // standard library objets #include <iostream> #include <vector> @@ -62,17 +81,24 @@ const std::string g_strNoDataSet = "(no data set)"; //============================================================================= enum FilterOption { - // Apply on ZLIB filter + //! Apply on ZLIB filter compression_level, - // BitShuffle filter + //! BitShuffle filter bitshuffle_compression, // default is BSHUF_H5_COMPRESS_LZ4 bitshuffle_block_size }; -/// Filter options to be passed with CreateCompressedDataSet method +//! Filter options to be passed with CreateCompressedDataSet method typedef std::map<FilterOption, int> FilterConfig; +//! \brief List of known compression filters +//! +//! This enumerate all known filter but all filters are not +//! necesseraly implemented. Check filter availability using the free functions +//! IsCompressFilterAvailable & AvailableCompressFilters +//! \see IsCompressFilterAvailable +//! \see AvailableCompressFilters enum CompressionFilter { CompressNone, // No compression @@ -84,17 +110,18 @@ enum CompressionFilter CompressBzip2, // bzip2 (not yet available) }; -/// Return 'true' if the given compression filter is currently available +//! Return 'true' if the given compression filter is currently available +//! \param filter_id filter identifier NEXUSCPP_DECL bool IsCompressFilterAvailable(CompressionFilter filter_id); /// Return the available compress filters NEXUSCPP_DECL std::set<CompressionFilter> AvailableCompressFilters(); //============================================================================= -/// NexusGlobalLock -/// -/// Ensure exclusive access to the nexus file API during the scope of each instance -/// of this class +// NexusGlobalLock +// +// Ensure exclusive access to the nexus file API during the scope of each instance +// of this class //============================================================================= class NexusGlobalLock { @@ -106,7 +133,7 @@ public: // Forward declaration class NexusFileImpl; -/// NeXus data types (see napi.h) +// NeXus data types (see napi.h) enum NexusDataType { NX_NONE = 0, /// Value not defined in the NeXus API @@ -122,21 +149,21 @@ enum NexusDataType NX_INT64 = 26, NX_UINT64 = 27, NX_BINARY = 21, - /// Logical data types (not defined in NeXus API) readed in NeXus meta-DTD files + // Logical data types (not defined in NeXus API) readed in NeXus meta-DTD files ISO8601 = 100, /// (NX_CHAR) NX_INT = 102, /// generic integer type NX_FLOAT = 103 /// generic real type }; -/// NeXus return codes +//! NeXus return codes enum NexusRC { NX_OK = 1, NX_EOD = -1, - NX_ITEM_NOT_FOUND = -2 /// Value not defined in the NeXus API + NX_ITEM_NOT_FOUND = -2 //! Value not defined in the NeXus API }; -/// Create access types +// Create access types enum ENexusCreateMode { NX_HDF4 = 0, @@ -144,12 +171,13 @@ enum ENexusCreateMode NX_XML // Not implemented yet }; -const int MAX_RANK = 32; // Max rank +//! Max datasets rank +const int MAX_RANK = 32; //============================================================================= -/// NeXus exceptions -/// -/// This class is designed to hold nexus exceptions +//! NeXus exceptions +//! +//! This class is designed to hold nexus exceptions //============================================================================= class NEXUSCPP_DECL NexusException: public yat::Exception { @@ -162,21 +190,20 @@ public: NexusException(const std::string& desc, const char *pcszOrigin): yat::Exception("NEXUSCPP_ERROR", desc.c_str(), pcszOrigin) {} - /// Prints error message on console + //! Prints error message on console void PrintMessage(); - /// Copies error message in a pre-allocated std::string buffer - /// - /// @param pBuf Buffer (allocated by caller) to copy the message in - /// @param iLen Buffer length - /// + //! Copies error message in a pre-allocated std::string buffer + //! + //! \param pBuf Buffer (allocated by caller) to copy the message in + //! \param iLen Buffer length void GetMsg(char *pBuf, int iLen); }; //============================================================================= -/// NeXus item identifier -/// -/// This class holds a nexus item ids +//! NeXus item identifier +//! +//! This class holds a nexus item id //============================================================================= class NEXUSCPP_DECL NexusItemID { @@ -191,9 +218,9 @@ public: }; //============================================================================= -/// NeXus Data set info -/// -/// This class allow manipulation of NeXus Data sets and subsets +//! NeXus Data set info +//! +//! This class allow manipulation of NeXus Data sets and subsets //============================================================================= class NEXUSCPP_DECL NexusDataSetInfo { @@ -207,74 +234,67 @@ protected: public: - /// Returns size according to a data type + //! Returns size according to a data type static int DataTypeSize(NexusDataType eDataType); - /// Constructor + //! Constructor NexusDataSetInfo(); - /// Destructor + //! Destructor ~NexusDataSetInfo(); - /// Sets datas - /// - /// @param eDataType Data type - /// @param iRank Data rank - /// + //! Sets datas + //! + //! \param eDataType Data type + //! \param iRank Data rank void SetInfo(NexusDataType eDataType, int iRank); - /// Clears instance + //! Clears instance void Clear(); //----------------------------------------------------------------- - /// @name Accessors + //! \name Accessors //@{ - /// Returns the data type + //! Returns the data type NexusDataType DataType() const { return m_eDataType; } - /// Returns the data set rank + //! Returns the data set rank int Rank() const { return m_iRank; } - /// Returns the whole data set rank + //! Returns the whole data set rank int TotalRank() const { return m_iTotalRank; } - /// Returns size array of dimensions - /// + //! Returns size array of dimensions int *DimArray() const { return m_piDim; } - /// Returns size array of dimensions of the whole dataset - /// @note can be bigger than the storage array of this NexusDataSetInfo - /// + //! Returns size array of dimensions of the whole dataset + //! \remark can be bigger than the storage array of this NexusDataSetInfo int *TotalDimArray() const { return m_piTotalDim; } - /// Set the whole dataset dimension's sizes - /// - /// @param iRankSpace Rank of the whole dataset - /// @param piDimArray Dimension sizes of the whole dataset - /// + //! Set the whole dataset dimension's sizes + //! + //! \param iTotalRank Rank of the whole dataset + //! \param piTotalDim Dimension sizes of the whole dataset void SetTotalDim(int iTotalRank, int *piTotalDim); - /// Returns total size - /// + //! Returns total size int Size() const; - /// Returns 'true' if no data set info is stored - /// + //! Returns 'true' if no data set info is stored bool IsEmpty() const; - /// Returns datum size - /// + //! Returns datum size unsigned int DatumSize() const; - /// Returns buffer size + //! Returns buffer size unsigned int BufferSize() const { return Size() * DatumSize(); } - /// Returns array of indices of starting values in Ith dimension - /// + //! Returns array of indices of starting values in Ith dimension int *StartArray() const { return m_piStart; } int *StartArray(); + //! Is the dataset info about a subset? bool IsSubset() const { return m_piStart ? true:false;} //@} Accessors @@ -292,79 +312,79 @@ private: bool m_owner; // ownsership public: - /// Constructors + //! Default c-tor NexusDataSet(); + + //! Copy c-tor NexusDataSet(const NexusDataSet &dataset); + + //! c-tor + //! + //! \param eDataType datatype + //! \param pData raw data + //! \param iRank number of dimensions + //! \param piDim pointer to the dimensions array + //! \param piStart if not null pointer to the start position of this subset NexusDataSet(NexusDataType eDataType, void *pData, int iRank, int *piDim, int *piStart=NULL); - /// Destructor - /// @note the data pointor is also deleted do not delete it another time + //! Destructor + //! \remark the data pointor is also deleted do not delete it another time ~NexusDataSet(); - /// Free data block - /// + //! Free data block void FreeData(); - /// Clears data set + //! Clears data set void Clear(); - /// Allocate the data set, according to the NexusDataSetInfo part - /// + //! Allocate the data set, according to the NexusDataSetInfo part void Alloc(); - /// Gives ownership or not - /// - /// By default the NexusDataset own the data pointer - /// @param this_has_ownership if false the NexusDataset is no longer the owner - /// + //! Gives ownership or not. By default the NexusDataset own the data pointer + //! + //! \param this_has_ownership if false the NexusDataset is no longer the owner void SetOwner(bool this_has_ownership); - /// Have ownership on data buffer ? - /// - /// By default the NexusDataset own the data pointer - /// @param this_has_ownership if false the NexusDataset is no longer the owner - /// + //! Have ownership on data buffer ? + //! bool IsOwner() { return m_owner; } //----------------------------------------------------------------- - /// @name Accessors + //! \name Accessors //@{ - /// Returns a pointer to the data set + //! Returns a pointer to the data set void *Data() const { return m_pData; } - /// Returns size of the data block (i.e. Size() * sizeof(<datatype>) ) + //! Returns size of the data block (i.e. Size() * sizeof(<datatype>) ) unsigned int MemSize() const; - /// Returns the number of items + //! Returns the number of items unsigned int Size() const; - /// Sets datas - /// - /// @param pParam data pointer we take ownership - /// + //! Sets data + //! + //! \param pData data pointer we take ownership void SetData(void *pData) { m_pData = pData; } - /// Sets datas - /// - /// @param pData Pointer to data to copy - /// @param eDataType Data type - /// @param iRank Number of dimension - /// @param piDimArray Dimensions sizes - /// + //! Sets data + //! + //! \param pData Pointer to data to copy + //! \param eDataType Data type + //! \param iRank Number of dimension + //! \param piDimArray Dimensions sizes void SetData(const void *pData, NexusDataType eDataType, int iRank, int *piDimArray); - /// Sets one dimension size - /// - /// iDim Dimension in range [0, 32[ - /// iSize Dimension size - /// + //! Sets one dimension size + //! + //! \param iDim Dimension in range [0, 32[ + //! \param iSize Dimension size void SetDimension(int iDim, int iSize); //@} Accessors //============================================================================= - /// Basic iterator to browse over NeXusDataSet values + //! Basic iterator to browse over NeXusDataSet values //============================================================================= template <class T> class Iterator { @@ -373,13 +393,15 @@ public: char *m_pDataItem; public: - /// Constructor + //! Constructor + //! + //! \param DataSet data set on which the iterator will iterate Iterator(const NexusDataSet &DataSet) : m_DataSet(DataSet) { m_pDataItem = (char *)DataSet.Data(); } - /// Return current value + //! Return current value T Value() const { switch( m_DataSet.DataType() ) @@ -404,24 +426,24 @@ public: return T(0); } - /// Dereferencing operator + //! Dereferencing operator T operator *() { return Value(); } - /// Post-incrementation operator + //! Post-incrementation operator Iterator operator++(int) { m_pDataItem += m_DataSet.DatumSize(); return *this; } - /// Pre-incrementation operator + //! Pre-incrementation operator Iterator operator++() { m_pDataItem += m_DataSet.DatumSize(); return *this; } - /// Is end of buffer reached ? + //! Is end of buffer reached ? bool End() const { return m_pDataItem == (char *)m_DataSet.Data() + m_DataSet.MemSize(); @@ -430,10 +452,10 @@ public: }; //============================================================================= -/// NeXus item info -/// -/// This class is used to store info about founded groups while -/// browsing a group level +//! NeXus item info +//! +//! This class is used to store info about founded groups while +//! browsing a group level //============================================================================= class NEXUSCPP_DECL NexusItemInfo { @@ -446,45 +468,45 @@ private: void *m_pContext; // Extra Data storing current context public: - /// Constructor + //! Constructor NexusItemInfo(); - /// Destructor + //! Destructor ~NexusItemInfo(); //----------------------------------------------------------------- /// Accessors //@{ - /// Returns name of NeXus data item (group or set) + //! Returns name of NeXus data item (group or set) const char *ItemName() const { return m_pszItem; } - /// Returns class name of NeXus group + //! Returns class name of NeXus group const char *ClassName() const { return m_pszClass; } - /// Returns the data type + //! Returns the data type NexusDataType DataType() const { return m_eDataType; } - /// Returns 'true' id the item is a data set + //! Returns 'true' id the item is a data set bool IsDataSet() const; - /// Returns 'true' id the item is a group + //! Returns 'true' id the item is a group bool IsGroup() const; //@} Accessors }; -/// Smart pointer definition helper +//! Smart pointer definition helper typedef yat::SharedPtr<NexusItemInfo> NexusItemInfoPtr; -/// ItemInfo smart pointers list definition helper +//! ItemInfo smart pointers list definition helper typedef std::list<NexusItemInfoPtr> NexusItemInfoList; //============================================================================= -/// NeXus Attribute info -/// -/// This class is used to store info about founded attributes while browsing -/// a group level +//! NeXus Attribute info +//! +//! This class is used to store info about founded attributes while browsing +//! a group level //============================================================================= class NEXUSCPP_DECL NexusAttrInfo { @@ -498,16 +520,13 @@ protected: public: #if ! defined(OBSOLETE_HDF5_WORKAROUND) - /// Constructor + //! Constructor NexusAttrInfo(); - /// Destructor + //! Destructor ~NexusAttrInfo(); #else - /// Constructor NexusAttrInfo() {}; - - /// Destructor ~NexusAttrInfo() {}; #endif @@ -515,23 +534,23 @@ public: /// Accessors //@{ - /// Returns name of NeXus attribute + //! Returns name of NeXus attribute const char *AttrName() const { return m_pszName; } - /// Returns len of attribute + //! Returns len of attribute int Len() const { return m_iLen; } - /// Returns type attribute data + //! Returns type attribute data NexusDataType DataType() const { return m_eDataType; } //@} Accessors }; //============================================================================= -/// NeXus Attribute -/// -/// This class is used to store info about founded attributes while browsing -/// a group level +//! NeXus Attribute +//! +//! This class is used to store info about founded attributes while browsing +//! a group level //============================================================================= class NEXUSCPP_DECL NexusAttr: public NexusAttrInfo { @@ -539,60 +558,74 @@ private: void * m_pAttrValue; public: + //! c-tor + //! + //! \param strName attribute name NexusAttr(const std::string &strName); + + //! Copy c-tor NexusAttr(const NexusAttr &aAttr); ~NexusAttr(); - /// Sets a value of type 'long' + //! Sets a value of type 'long' void SetLong(long lValue); - /// Sets a value of type 'C characters std::string' + //! Sets a value of type + //! + //! \param pcszValue C-style string attribute value void SetCString(const char *pcszValue); - /// Sets a value of type 'STL std::string' + //! Sets a value of type 'STL std::string' + //! + //! \param strValue attribute value void SetString(const std::string &strValue); - /// Sets a value of type 'double' + //! Sets a value of type 'double' + //! + //! \param dValue attribute value void SetDouble(double dValue); - /// Sets a value of type 'float' + //! Sets a value of type 'float' + //! + //! \param fValue attribute value void SetFloat(float fValue); - /// Get 'long' type value + //! Get 'long' type value long GetLong() const; - /// Gets 'double' type value + //! Gets 'double' type value double GetDouble() const ; - /// Gets 'float' type value + //! Gets 'float' type value float GetFloat() const; - /// Gets 'std::string' type value + //! Gets 'std::string' type value std::string GetString() const; - /// Returns the attr buffer + //! Returns the attr buffer void *RawValue() const; private: void CopyValue(const NexusAttr &aAttr); }; -/// definition of a attribute collection +//! definition of a attribute collection typedef std::list<NexusAttr> NeXusAttrList; //============================================================================= -/// NeXus File Class -/// -/// This class allow manipulation of NeXus File with no need to known about -/// nexus file handle -/// @note This is wrapper class, the real job is make by a internal objet +//! NeXus File Class +//! +//! This class allow manipulation of NeXus File with no need to known about +//! nexus file handle +//! \remark This is wrapper class, the real job is make by a internal objet //============================================================================= class NEXUSCPP_DECL NexusFile { public: + //! Files open mode enum OpenMode { - NONE, + NONE, //! no mode specified READ, WRITE }; @@ -605,24 +638,23 @@ public: static const bool USE_LOCK = true; - /// Initialize the HDF5 context - /// It is safe to call this function multiple times - /// @note Any constructed NexusFile will initialize - + // Initialize the HDF5 context static void Initialize(); #if ! defined(OBSOLETE_HDF5_WORKAROUND) - /// @name Constructors and destructor + //! \name Constructors and destructor //@{ - /// Constructor - /// - /// @param pcszFullPath path + complete filename + //! Constructor + //! + //! \param pcszFullPath path + complete filename + //! \param eMode OpenMode (NONE/READ/WRITE) + //! \param use_lock if 'true' then use file-system locking for each file access NexusFile(const char *pcszFullPath=NULL, OpenMode eMode = NONE, bool use_lock = false); - /// Destructor - /// - /// Perform all operations needed such as closing open groups + //! Destructor + //! + //! Perform all operations needed such as closing open groups ~NexusFile(); #else @@ -633,99 +665,93 @@ public: //@} //----------------------------------------------------------------- - /// @name File manipulation methods + //! \name File manipulation methods //@{ - /// Creating file - /// - /// Create Nexus file based on HDF4 library - /// - /// @param pcszFullPath path + complete filename - /// @param eMode creating mode can be NX_HDF4, NX_HDF5 or NX_XML - /// + //! Creating file + //! + //! Create Nexus file + //! + //! \param pcszFullPath path + complete filename + //! \param eMode creating mode can be NX_HDF5, NX_HDF4 or NX_XML + //! \remark HDF4 and XML file modes are deprecated + //! void Create(const char *pcszFullPath, ENexusCreateMode eMode = NX_HDF5); - /// Opens an existing file for read operations - /// - /// @param pcszFullPath path + complete filename - /// + //! Opens an existing file for read operations + //! + //! \param pcszFullPath path + complete filename void OpenRead(const char *pcszFullPath); - /// Opens an existing file for read/write operations - /// - /// @param pcszFullPath path + complete filename - /// + //! Opens an existing file for read/write operations + //! + //! \param pcszFullPath path + complete filename void OpenReadWrite(const char *pcszFullPath); - /// Closes currently opened file - /// Frees all allocated objects (groups & data sets) - /// + //! Closes currently opened file + //! Frees all allocated objects (groups & data sets) void Close(); - /// Flush - /// Flushes all data to the NeXus file - /// + //! Flushes all data to the NeXus file void Flush(); //@} //----------------------------------------------------------------- - /// @name groups manipulations + //! \name groups manipulations //@{ - /// Adds a new group - /// - /// The new group is added under the currently opened group - /// If no group is already open add the group at the top-level - /// (hope this is a NXentry group) - /// - /// @param pcszName Group name - /// @param pcszClass NeXus class - /// @param bOpen If 'true' automatically open the group - /// + //! Adds a new group + //! + //! The new group is added under the currently opened group + //! If no group is already open add the group at the top-level + //! (hope this is a NXentry group) + //! + //! \param pcszName Group name + //! \param pcszClass NeXus class + /// \param bOpen If 'true' automatically open the group void CreateGroup(const char *pcszName, const char *pcszClass, bool bOpen=true); - /// Opens a existing group - /// - /// @param pcszName Group name - /// @param pcszClass NeXus class - /// @param bThrowException if true this method may throw a exception - /// @return - /// + //! Opens a existing group + //! + //! \param pcszName Group name + //! \param pcszClass NeXus class + //! \param bThrowException if true this method may throw a exception + //! \return bool OpenGroup(const char *pcszName, const char *pcszClass, bool bThrowException=true); - /// Closes current group - /// + //! Closes current group void CloseGroup(); - /// Closes all opened groups - /// + //! Closes all opened groups void CloseAllGroups(); //@} groups manipulations //----------------------------------------------------------------- - /// @name data sets manipulations + //! \name data sets manipulations //@{ - /// Creates data set - /// - /// @param pcszName Data set name - /// @param eDataType Data type - /// @param iRank Data set rank - /// @param piDim Pointer to array of dimensions - /// + //! Creates data set + //! + //! \param pcszName Data set name + //! \param eDataType Data type + //! \param iRank Data set rank + //! \param piDim Pointer to array of dimensions + //! \param bOpen If 'true' keep the data set open after its creation void CreateDataSet(const char *pcszName, NexusDataType eDataType, int iRank, int *piDim, int bOpen=true); - /// Creates compressed data set - /// - /// @param pcszName Data set name - /// @param eDataType Data type (see napi.h) - /// @param iRank Data set rank - /// @param piDim Pointer to array of dimensions - /// @param piChunkDim Pointer to array of chunk dimensions - /// + //! Creates compressed data set + //! + //! \param pcszName Data set name + //! \param eDataType Data type (see napi.h) + //! \param iRank Data set rank + //! \param piDim Pointer to array of dimensions + //! \param piChunkDim Pointer to array of chunk dimensions + //! \param filter compression filter to apply + //! \param filter_config filter parameters + //! \param bOpen If 'true' keep the data set open after its creation void CreateCompressedDataSet(const char *pcszName, NexusDataType eDataType, int iRank, int *piDim, int *piChunkDim, CompressionFilter filter=CompressZLIB, @@ -735,227 +761,246 @@ public: /// void CloseDataSet(); - /// Quickly creates simple data set and writes the data - /// - /// @param pcszName Data set name - /// @param pData pointer to value - /// @param piDim Pointer to array of dimensions sizes - /// @param eDataType NeXus Data type (see napi.h) - /// @param iRank Dimensions count - /// @param bCreate true for creating the dataset before write data otherwise - /// we suppose the dataset already created and opened - /// + //! Writes data into a new or existing dataset + //! + //! \param pcszName Data set name + //! \param pData pointer to value + //! \param eDataType NeXus Data type (see napi.h) + //! \param iRank Dimensions count + //! \param piDim Pointer to array of dimensions sizes + //! \param bCreate true for creating the dataset before write data otherwise + //! we suppose the dataset already created and opened void WriteData(const char *pcszName, void *pData, NexusDataType eDataType, int iRank, int *piDim, bool bCreate=true); + //! Writes data into a new or existing dataset + //! + //! \param pcszName Data set name + //! \param pData pointer to value + //! \param eDataType NeXus Data type (see napi.h) + //! \param Shape Dimensions arrau + //! \param bCreate true for creating the dataset before write data otherwise + //! we suppose the dataset already created and opened void WriteData(const char *pcszName, void *pData, NexusDataType eDataType, const std::vector<std::size_t>& Shape, bool bCreate=true); + //! Writes data subset into a new or existing dataset + //! + //! \param pcszName Data set name + //! \param pData pointer to value + //! \param eDataType NeXus Data type + //! \param iRank Dimensions count + //! \param piStart Pointer to array of start positions of the subset + //! \param piDim Pointer to array of dimensions sizes + //! \param bCreate true for creating the dataset before write data otherwise + //! we suppose the dataset already created and opened + //! \param bNoDim deprecated parameter, must be 'false' void WriteDataSubSet(const char *pcszName, void *pData, NexusDataType eDataType, int iRank, int *piStart, int *piDim, bool bCreate=true, bool bNoDim = false); - /// 'float' version of #WriteData + //! 'float' version of #WriteData void WriteData(const char *pcszName, float fValue, bool bCreate=true); - /// 'double' version of #WriteData + //! 'double' version of #WriteData void WriteData(const char *pcszName, double dValue, bool bCreate=true); - /// 'long' version of #WriteData + //! 'long' version of #WriteData void WriteData(const char *pcszName, long lValue, bool bCreate=true); - /// 'std::string' version of #WriteData + //! 'std::string' version of #WriteData void WriteData(const char *pcszName, const char *pcszValue, bool bCreate=true); - /// 'binary' version of #WriteData + //! 'binary' version of #WriteData void WriteData(const char *pcszName, void *pData, int _iLen, bool bCreate=true); - /// Opens a already existing data set - /// - /// @param pcszName Data set name + //! Opens a already existing data set + //! + //! \param pcszName Data set name + //! \param bThrowException If 'true' thrown an exception in case of error bool OpenDataSet(const char *pcszName, bool bThrowException=true); - /// Puts data in the currently open data set - /// - /// @param pData Pointer to the data bloc - /// @param pcszName Data set name - /// - /// @note Use pcszName to specify another data set - /// + //! Puts data in the currently open data set + //! + //! \param pData Pointer to the data bloc + //! \param pcszName Data set name + //! \param bFlush If 'true' then immediately flush the data to the file + //! \remark Use pcszName to specify another data set void PutData(void *pData, const char *pcszName=NULL, int bFlush=false); - /// Puts data subset in the currently open data set - /// - /// @param pData Pointer to the data bloc - /// @param piStart Indices of starting values in each dimension - /// @param piSize Length of subset in each dimension - /// @param pcszName Data set name - /// - /// @note Use pcszName to specify another data set - /// + //! Puts data subset in the currently open data set + //! + //! \param pData Pointer to the data bloc + //! \param piStart Indices of starting values in each dimension + //! \param piSize Length of subset in each dimension + //! \param pcszName Data set name + //! \remark Use pcszName to specify another data set void PutDataSubSet(void *pData, int *piStart, int *piSize, const char *pcszName=NULL); //----------------------------------------------------------------- - /// @name Data set reading + //! \name Data set reading //@{ - /// Reads data values from a data set in currently open group - /// - /// @param pDataSet a pointer to a NexusDataSet instanciate by caller - /// @param pcszDataSet Data set name - /// @note if the data set name isn't provided, supposes that pDataSet isn't empty - /// + //! Reads data values from a data set in currently open group + //! + //! \param pDataSet a pointer to a NexusDataSet instanciate by caller + //! \param pcszDataSet Data set name + //! \remark if the data set name isn't provided, supposes that pDataSet isn't empty void GetData(NexusDataSet *pDataSet, const char *pcszDataSet=NULL); - /// Reads data values from a data set in currently open group - /// - /// @param pDataSet a pointer to a NexusDataSet instanciate by caller - /// @param pcszDataSet Data set name - /// @note if the data set name isn't provided, supposes that pDataSet isn't empty - /// + //! Reads data values from a data set in currently open group + //! + //! \param pDataSet a pointer to a NexusDataSet instanciate by caller + //! \param pcszDataSet Data set name + //! \note if the data set name isn't provided, supposes that pDataSet isn't empty void GetDataSubSet(NexusDataSet *pDataSet, const char *pcszDataSet=NULL); - /// Gets info about a data set - /// - /// @param pDataSetInfo a pointer to a NexusDataSetInfo instanciate by caller - /// @param pcszDataSet Data set name - /// + //! Gets info about a data set + //! + //! \param pDataSetInfo a pointer to a NexusDataSetInfo instanciate by caller + //! \param pcszDataSet Data set name void GetDataSetInfo(NexusDataSetInfo *pDataSetInfo, const char *pcszDataSet); //@} data sets manipulations //----------------------------------------------------------------- - /// @name Getting attributes + //! \name Getting attributes //@{ - /// Gets a attribute - /// - /// @param pcszAttr Attribute name - /// @param piBufLen Pointer to BufLen - /// @param pData Pointer to attribute value buffer - /// @param eDataType Attribute data value type - /// - /// @note The caller is responsible for allocating enough memory - /// for the attribute values + //! Gets a attribute + //! + //! \param pcszAttr Attribute name + //! \param piBufLen Pointer to BufLen + //! \param pData Pointer to attribute value buffer + //! \param eDataType Attribute data value type + //! + //! \remark The caller is responsible for allocating enough memory + //! for the attribute values void GetAttribute(const char *pcszAttr, int *piBufLen, void *pData, NexusDataType eDataType); - /// Gets a 'long' attribute. Call - /// - /// @param pcszAttr Attribute name - /// @param plValue Pointer to attribute value buffer - /// - /// @note The caller is responsible for allocating enough memory - /// for the attribute values + //! Gets a 'long' attribute. Call + //! + //! \param pcszAttr Attribute name + //! \param plValue Pointer to attribute value buffer + //! + //! \remark The caller is responsible for allocating enough memory + //! for the attribute values void GetAttribute(const char *pcszAttr, long *plValue); - /// Gets a 'double' attribute - /// - /// @param pcszAttr Attribute name - /// @param pdValue Pointer to attribute value buffer - /// - /// @note The caller is responsible for allocating enough memory - /// for the attribute values + //! Gets a 'double' attribute + //! + //! \param pcszAttr Attribute name + //! \param pdValue Pointer to attribute value buffer + //! + //! \remark The caller is responsible for allocating enough memory + //! for the attribute values void GetAttribute(const char *pcszAttr, double *pdValue); - /// Gets a 'float' attribute - /// - /// @param pcszAttr Attribute name - /// @param pfValue Pointer to attribute value buffer - /// - /// @note The caller is responsible for allocating enough memory - /// for the attribute values + //! Gets a 'float' attribute + //! + //! \param pcszAttr Attribute name + //! \param pfValue Pointer to attribute value buffer + //! + //! \remark The caller is responsible for allocating enough memory + //! for the attribute values void GetAttribute(const char *pcszAttr, float *pfValue); - /// Gets a 'std::string' attribute - /// - /// @param pcszAttr Attribute name - /// @param pstrValue Pointer to attribute value - /// + //! Gets a 'std::string' attribute + //! + //! \param pcszAttr Attribute name + //! \param pstrValue Pointer to attribute value void GetAttribute(const char *pcszAttr, std::string *pstrValue); //@} Getting attributes //----------------------------------------------------------------- - /// @name Putting attributes - /// Writes an attribute of the currently open data set. - /// If no data set is open, a global attribute is generated. - /// The attribute has both a name and a value. - /// @param pcszName Data set name - /// @param pValue pointer to value - /// @param iLen Value buffer length - /// @param eDataType NeXus Data type (see napi.h) + //! \name Putting attributes + //! Writes an attribute of the currently open data set. + //! If no data set is open, a global attribute is generated. + //! The attribute has both a name and a value. //@{ - /// Generic method for putting attribute + //! Generic method for putting attribute + //! + //! \param pcszName Data set name + //! \param pValue pointer to value + //! \param iLen Value buffer length + //! \param eDataType NeXus Data type (see napi.h) void PutAttr(const char *pcszName, void *pValue, int iLen, NexusDataType eDataType); - /// Puts a attribute of type 'long' + //! Puts a attribute of type 'long' + //! + //! \param pcszName attribute name + //! \param lValue attribute value void PutAttr(const char *pcszName, long lValue); - /// Puts a attribute of type 'std::string' + //! Puts a attribute of type 'C-style string' + //! + //! \param pcszName attribute name + //! \param pcszValue attribute value void PutAttr(const char *pcszName, const char *pcszValue); - /// Puts a attribute of type 'double' + //! Puts a attribute of type 'double' + //! + //! \param pcszName attribute name + //! \param dValue attribute value void PutAttr(const char *pcszName, double dValue); - /// Puts a attribute of type 'float' + //! Puts a attribute of type 'float' + //! + //! \param pcszName attribute name + //! \param fValue attribute value void PutAttr(const char *pcszName, float fValue); //@} // Putting attributes //----------------------------------------------------------------- - /// @name Browsing methods + //! \name Browsing methods //@{ - /// Get the number of items in the current group + //! Get the number of items in the current group int ItemCount(); - /// Get the number of attributes in the current data set + //! Get the number of attributes in the current data set int AttrCount(); - /// Get info about the first item (data set or group) in the current group - /// - /// @param pItemInfo Pointer to NexusItemInfo used to store info - /// - /// @return NX_OK if data set found - /// NX_EOD if not - /// + //! Get info about the first item (data set or group) in the current group + //! + //! \param pItemInfo Pointer to NexusItemInfo used to store info + //! \return NX_OK if data set found + //! NX_EOD if not int GetFirstItem(NexusItemInfo *pItemInfo); - /// Get info about the next item (data set or group) in the current group - /// - /// @param pItemInfo Pointer to NexusItemInfo used to store info - /// - /// @return NX_OK if data set found - /// NX_EOD if not - /// + //! Get info about the next item (data set or group) in the current group + //! + //! \param pItemInfo Pointer to NexusItemInfo used to store info + //! \return NX_OK if data set found + //! NX_EOD if not int GetNextItem(NexusItemInfo *pItemInfo); - /// Get info about the first attribute of the specified data set - /// - /// @param pAttrInfo Pointer to a NexusAttrInfo object - /// @param pcszDataSet Name of the data set to search in - /// @return NX_OK if group found, - /// NX_EOD if not - /// - /// @note if pcszDataSet is NULL searching will be performed in currently open - /// data set or in global attribute std::list if no data set is open - /// @note You must call GetFirstAttribute in order to initialize the search process - /// then call GetNextAttribute for retrieving information about the remaining - /// attributes - /// + //! Get info about the first attribute of the specified data set + //! + //! \param pAttrInfo Pointer to a NexusAttrInfo object + //! \param pcszDataSet Name of the data set to search in + //! \return NX_OK if group found, + //! NX_EOD if not + //! + //! \remark if pcszDataSet is NULL searching will be performed in currently open + //! data set or in global attribute std::list if no data set is open + //! \remark You must call GetFirstAttribute in order to initialize the search process + //! then call GetNextAttribute for retrieving information about the remaining + //! attributes int GetFirstAttribute(NexusAttrInfo *pAttrInfo, const char *pcszDataSet=NULL); - /// Get info about the next attribute of the specified data set - /// - /// @param pAttrInfo Pointer to a NexusAttrInfo object - /// @return NX_OK if group found - /// NX_EOD if not - /// - /// @note You must call GetFirstAttribute in order to initialize the search process - /// then call GetNextAttribute for retrieving information about the remaining - /// attributes - /// + //! Get info about the next attribute of the specified data set + //! + //! \param pAttrInfo Pointer to a NexusAttrInfo object + //! \return NX_OK if group found + //! NX_EOD if not + //! + //! \remark You must call GetFirstAttribute in order to initialize the search process + //! then call GetNextAttribute for retrieving information about the remaining + //! attributes int GetNextAttribute(NexusAttrInfo *pAttrInfo); //@} // Browsing methods @@ -964,204 +1009,180 @@ public: /// @name Item linking methods //@{ - /// Get a handle on the currently open data set in order to link it with a group - /// - /// @return a pointer to the handle, or NULL if no data set is open or no file is open - /// + //! Get a handle on the currently open data set in order to link it with a group + //! + //! \return a pointer to the handle, or NULL if no data set is open or no file is open void GetDataSetLink(NexusItemID *pnxl); - /// Get a handle on the currently open group set in order to link it with a group - /// - /// @return a pointer to the handle, or NULL if no file is open - /// + //! Get a handle on the currently open group set in order to link it with a group + //! + //! \return a pointer to the handle, or NULL if no file is open void GetGroupLink(NexusItemID *pnxl); - /// Link a item to the currently open group - /// - /// @param pItemHandle Handle of the item to link - /// + //! Link a item to the currently open group + //! + //! \param nxl Handle of the item to link void LinkToCurrentGroup(const NexusItemID &nxl); //@} // Item linking methods //----------------------------------------------------------------- - /// @name User pointer accessors + //! \name User pointer accessors //@{ - /// Get user pointer + //! Get user pointer void *UserPtr() const { return m_pUserPtr; } - /// Set user pointer + //! Set user pointer void SetUserPtr(void *p) { m_pUserPtr = p; } //@} // User pointer accessors //----------------------------------------------------------------- - /// @name high level methods + //! \name high level methods //@{ - /// Opens a existing group from a given path - /// - /// @param pszPath path to group in the form : /<NXroot>/{Group name}<{group class}>/... - /// if no group name is specified then open the first group for the given class - /// example : /<NXroot>/scan_1<NXentry>/<NXdata> - /// @param bThrowException if true this method may throw a exception - /// @return true if group has been succefully open - /// + //! Opens a existing group from a given path + //! + //! \param pszPath path to group in the form : /<NXroot>/{Group name}<{group class}>/... + //! if no group name is specified then open the first group for the given class + //! example : "/<NXroot>/scan_1<NXentry>/<NXdata>" + //! \param bThrowException if true this method may throw a exception + //! \return true if group has been succefully open bool OpenGroupPath(const char *pszPath, bool bThrowException=true); - /// Create and open a group from a given path - /// This method may throw a exception - /// - /// @param pszPath path to group in the form : /<NXroot>/{Group name}<{group class}>/... - /// if no group name is specified then open the first group for the given class - /// example : /<NXroot>/scan_1<NXentry>/<NXdata> - /// + //! Create and open a group from a given path + //! This method may throw a exception + //! + //! \param pszPath path to group in the form : "/<NXroot>/{Group name}<{group class}>/..." + //! if no group name is specified then open the first group for the given class + //! example : "/<NXroot>/scan_1<NXentry>/<NXdata>" bool CreateGroupPath(const char *pszPath); - /// Search for all occurences of a group (name and class) starting at a given level on the hierarchy - /// - /// @param pszGroupName name of searched group - /// @param pszClassName class of searched group - /// @param pvecPaths output std::vector of found groups - /// @param pszStartPath path for starting research - /// @return NX_OK if at least one group was found - /// NX_EOD if not - /// + //! Search for all occurences of a group (name and class) starting at a given level on the hierarchy + //! + //! \param pszGroupName name of searched group + //! \param pszClassName class of searched group + //! \param pvecPaths output std::vector of found groups + //! \param pszStartPath path for starting research + //! \return NX_OK if at least one group was found + //! NX_EOD if not int SearchGroup(const char *pszGroupName, const char *pszClassName, std::vector<std::string> *pvecPaths, const char *pszStartPath=NULL); - /// Search for all occurences of a data set (name) with a given attribute - /// - /// @param pszAttrName name of looked attribute - /// @param pvecPaths output std::vector of found data sets - /// @param strAttrVal optionnal attribute value to match - /// @return NX_OK if at least one data set was found - /// NX_EOD if not - /// + //! Search for all occurences of a data set (name) with a given attribute + //! + //! \param pszAttrName name of looked attribute + //! \param pvecDataSets output std::vector of found data sets + //! \param strAttrVal optionnal attribute value to match + //! \return NX_OK if at least one data set was found + //! NX_EOD if not int SearchDataSetFromAttr(const char *pszAttrName, std::vector<std::string> *pvecDataSets, const std::string &strAttrVal=""); - /// Search for first occurence of a data set (name) with a given attribute - /// - /// @param pszAttrName name of looked attribute - /// @param pstrDataSet name of founded data set - /// @param strAttrVal optionnal attribute value to match - /// @return NX_OK if at least one data set was found - /// NX_EOD if not - /// + //! Search for first occurence of a data set (name) with a given attribute + //! + //! \param pszAttrName name of looked attribute + //! \param pstrDataSet name of founded data set + //! \param strAttrVal optionnal attribute value to match + //! \return NX_OK if at least one data set was found + //! NX_EOD if not int SearchFirstDataSetFromAttr(const char *pszAttrName, std::string *pstrDataSet, const std::string &strAttrVal=""); - /// Search for all occurences of a data set (name) with a given attribute - /// - /// @param pszAttrName name of looked attribute - /// @param iRank dataset rank - /// @param pvecPaths output std::vector of found data sets - /// @param strAttrVal optionnal attribute value to match - /// @return NX_OK if at least one data set was found - /// NX_EOD if not - /// + //! Search for all occurences of a data set (name) with a given attribute + //! + //! \param pszAttrName name of looked attribute + //! \param iRank dataset rank + //! \param pvecDataSets output std::vector of found data sets + //! \param strAttrVal optionnal attribute value to match + //! \return NX_OK if at least one data set was found + //! NX_EOD if not int SearchDataSetFromAttrAndRank(const char *pszAttrName, int iRank, std::vector<std::string> *pvecDataSets, const std::string &strAttrVal=""); - /// Search for all occurences of a data set (name) with a given attribute - /// - /// @param pszAttrName name of looked attribute - /// @param iRank dataset rank - /// @param pvecPaths output std::vector of found data sets - /// @param strAttrVal optionnal attribute value to match - /// @return NX_OK if at least one data set was found - /// NX_EOD if not - /// + //! Search for all occurences of a data set (name) with a given attribute + //! + //! \param pszAttrName name of looked attribute + //! \param iRank dataset rank + //! \param[out] pstrDataSet dataset name found + //! \param strAttrVal optionnal attribute value to match + //! \return NX_OK if at least one data set was found + //! NX_EOD if not int SearchFirstDataSetFromAttrAndRank(const char *pszAttrName, int iRank, std::string *pstrDataSet, const std::string &strAttrVal=""); - /// Gets a attribute as a std::string regardless of its type - /// - /// @param aAttrInfo Attribute info object - /// @return A STL std::string containing the value - /// + //! Gets a attribute as a string regardless of its type + //! + //! \param aAttrInfo Attribute info object + //! \return The value as string std::string GetAttributeAsString(const NexusAttrInfo &aAttrInfo); - /// Check if dataset has attribute - /// - /// @param pszAttrName Name of looked attribute - /// @param pcszDataSet (optionnal) Data set to open, if not specified look in currently opened dataset - /// @param strAttrVal optionnal attribute value to match - /// @return 'true' if sds has attribute, otherwise 'false' - /// + //! Check if dataset has attribute + //! + //! \param pszAttrName Name of looked attribute + //! \param pcszDataSet (optionnal) Data set to open, if not specified look in currently opened dataset + //! \param strAttrVal optionnal attribute value to match + //! \return 'true' if sds has attribute, otherwise 'false' bool HasAttribute(const char *pszAttrName, const char *pcszDataSet=NULL, const std::string &strAttrVal=""); - /// Gets a attribute as a std::string regardless of its type - /// - /// @param pszAttrName Attribute name - /// @param pcszDataSet Name of the data set containing the attributge - /// @param pstrValue std::string object to put the value in - /// @return true if attribute was found - /// + //! Gets a attribute as a std::string regardless of its type + //! + //! \param pszAttrName Attribute name + //! \param pcszDataSet Name of the data set containing the attributge + //! \param pstrValue std::string object to put the value in + //! \return true if attribute was found bool GetAttributeAsString(const char *pszAttrName, const char *pcszDataSet, std::string *pstrValue); - /// Build a dictionnary that contains axis datasets for each dimension belong to a given dataset - /// Entries in the dictionnary are in the form : - /// 'axis_<axis>_<primary>' = '<dataset name> - /// - /// @param vecvecAxis Vector of axis vectors that will contains the axis datasets name - /// @param pszGroup Group Path - /// @param pszDataSet DataSet name - /// - /// @return 'true' if at least one axis has been found - /// + //! Build a dictionnary that contains axis datasets for each dimension belong to a given dataset + //! Entries in the dictionnary are in the form : + //! "axis_<axis>_<primary>=<dataset name>"" + //! + //! \param pmapAxis Map of axis that will contains the axis datasets name + //! \param pszGroupPath Group Path + //! \param pcszDataSet DataSet name + //! \return 'true' if at least one axis has been found bool BuildAxisDict(std::map<std::string, std::string> *pmapAxis, const char *pszGroupPath=NULL, const char *pcszDataSet=NULL); - /// Build a dictionnary that contains axis values (readed and setted) datasets for each dimension belong to a given dataset - /// Entries in the dictionnary are in the form : - /// 'axis-readed_<axis>_<primary>' = '<dataset name> - /// 'axis-setted_<axis>_<primary>' = '<dataset name> - /// - /// @param vecvecAxis Vector of axis vectors that will contains the axis datasets name - /// @param pszGroup Group Path - /// @param pszDataSet DataSet name - /// - /// @return 'true' if at least one axis has been found - /// + //! Build a dictionnary that contains axis values (readed and setted) datasets for each dimension belong to a given dataset + //! Entries in the dictionnary are in the form : + //! "axis-readed_<axis>_<primary> = <dataset name>" + //! "axis-setted_<axis>_<primary> = <dataset name>" + //! + //! \param pmapAxis Map of axis that will contains the axis datasets name + //! \param pszGroupPath Group Path + //! \param pcszDataSet DataSet name + //! \return 'true' if at least one axis has been found bool BuildScanAxisDict(std::map<std::string, std::string> *pmapAxis, const char *pszGroupPath=NULL, const char *pcszDataSet=NULL); - /// Get scam dimension - /// - /// Reads NXdata group and look for variables datasets (with attribute axis) and return the - /// biggest axis attribute value (note that in time scan case axis may be seeted to 0) - /// - /// @param pszGroup Group Path - /// - /// @return scan dimension (time scans are 1D scans), or 0 if no axis datasets was found - /// + //! Get scam dimension + //! + //! Reads NXdata group and look for variables datasets (with attribute axis) and return the + //! biggest axis attribute value (note that in time scan case axis may be seeted to 0) + //! + //! \param pszDataGroupPath Group Path + //! + //! \return scan dimension (time scans are 1D scans), or 0 if no axis datasets was found int GetScanDim(const char *pszDataGroupPath); - /// Current Group Name - /// + //! Current Group Name std::string CurrentGroupName(); - /// Current Group Class - /// + //! Current Group Class std::string CurrentGroupClass(); - /// Currently opened group path inside NeXus file - /// + //! Currently opened group path inside NeXus file std::string CurrentGroupPath(); - /// Currently opened dataset - /// + //! Currently opened dataset std::string CurrentDataset(); - /// Returns the children of the currently opened group - /// - /// @param pvecDatasets empty std::vector for storing dataset names - /// @param pvecGroupNames empty std::vector for storing subgroups names - /// @param pvecGroupClasses empty std::vector for storing subgroups classes - /// + //! Returns the children of the currently opened group + //! + //! \param pvecDatasets empty std::vector for storing dataset names + //! \param pvecGroupNames empty std::vector for storing subgroups names + //! \param pvecGroupClasses empty std::vector for storing subgroups classes void GetGroupChildren(std::vector<std::string> *pvecDatasets, std::vector<std::string> *pvecGroupNames, std::vector<std::string> *pvecGroupClasses); - /// Returns the children of the currently opened group - /// - /// @return a list of NexusItemInfo object smart pointer (yat::SharedPtr) - /// + //! Returns the children of the currently opened group + //! + //! \return a list of NexusItemInfo object smart pointer (yat::SharedPtr) NexusItemInfoList GetGroupChildren(); //@} @@ -1170,7 +1191,7 @@ public: /// @name Deprecated methods //@{ - void GetAttribute(const char *pcszAttr, char *pszValue, int iBufLen); + void GetAttribute(const char*, char*, int); //@} diff --git a/include/nexuscpp/nxfinalizer.h b/include/nexuscpp/nxfinalizer.h index a851aef..4ccd2e3 100644 --- a/include/nexuscpp/nxfinalizer.h +++ b/include/nexuscpp/nxfinalizer.h @@ -1,11 +1,20 @@ -// ============================================================================ -// = CONTEXT -// Flyscan Project - Nexus file generation optimizer -// = File -// NexusDataStreamerFinalizer.h -// = AUTHOR -// N.Leclercq - SOLEIL -// ============================================================================ +//***************************************************************************** +/// Synchrotron SOLEIL +/// +/// NeXus C++ API +/// +/// Creation : 16/02/2005 +/// Authors : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud +/// +/// This program is free software; you can redistribute it and/or modify it under +/// the terms of the GNU General Public License as published by the Free Software +/// Foundation; version 2 of the License. +/// +/// This program is distributed in the hope that it will be useful, but WITHOUT +/// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +/// FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. +/// +//***************************************************************************** #pragma once @@ -19,13 +28,11 @@ namespace nxcpp const std::size_t kDEFAULT_PULSER_PERIOD = 3000; -//----------------------------------------------------------------------------- // Forward declaration -//----------------------------------------------------------------------------- class DataStreamer; //----------------------------------------------------------------------------- -// NexusDataStreamerFinalizer +//! NexusDataStreamerFinalizer //----------------------------------------------------------------------------- class NEXUSCPP_DECL NexusDataStreamerFinalizer { @@ -33,28 +40,28 @@ public: typedef struct Entry { - //---------------------------------------- - //- the nexuscpp::DataStreamer to finalize + //! The nexuscpp::DataStreamer to finalize nxcpp::DataStreamer *data_streamer; - //---------------------------------------- - //- opaque data holder - //- for data-items making use of the nexuscpp::DataStreamer::NO_COPY mode - //- this will be simply deleted once the data streaming is done - //- use this to ensure that the memory blocks containing data are not released before streaming is done + + //! Opaque data holder + //! for data-items making use of the nexuscpp::DataStreamer::NO_COPY mode + //! this will be simply deleted once the data streaming is done + //! use this to ensure that the memory blocks containing data are not released before streaming is done yat::Container *data_holder; - //---------------------------------------- - Entry () - : data_streamer(0), data_holder(0) {} - //---------------------------------------- - Entry (Entry& src) - : data_streamer(src.data_streamer), data_holder(src.data_holder) { src.data_streamer = 0; src.data_holder = 0; } - //---------------------------------------- + + //! default c-tor + Entry () : data_streamer(0), data_holder(0) {} + + //! Copy c-tot + Entry (Entry& src) : data_streamer(src.data_streamer), data_holder(src.data_holder) + { src.data_streamer = 0; src.data_holder = 0; } + + //! Copy operator void operator= (Entry& src) { data_streamer = src.data_streamer; src.data_streamer = 0; data_holder = src.data_holder; src.data_holder = 0; } - //---------------------------------------- - ~Entry () - { delete data_streamer; delete data_holder; } - //---------------------------------------- + + //! d-tor + ~Entry () { delete data_streamer; delete data_holder; } } Entry; //------------------------------------------------------- @@ -63,14 +70,15 @@ public: //------------------------------------------------------- virtual ~NexusDataStreamerFinalizer(); - //------------------------------------------------------- - //! \param pulser_period finalizer period in ms + //! Start the finalyser + //! + //! \param period_ms finalizer period in ms void start(std::size_t period_ms = kDEFAULT_PULSER_PERIOD); - //------------------------------------------------------- + //! Stop the finalyser void stop(); - //------------------------------------------------------- + //! Push a datastreamer entry void push(Entry* e); private: diff --git a/include/nexuscpp/nxwriter.h b/include/nexuscpp/nxwriter.h index 7845a1d..6e594ce 100644 --- a/include/nexuscpp/nxwriter.h +++ b/include/nexuscpp/nxwriter.h @@ -1,10 +1,10 @@ //***************************************************************************** /// Synchrotron SOLEIL /// -/// NeXus C++ API over NAPI +/// NeXus C++ API /// -/// Creation : 2010/07/18 -/// Author : Stephane Poirier +/// Creation : 16/02/2005 +/// Authors : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud /// /// This program is free software; you can redistribute it and/or modify it under /// the terms of the GNU General Public License as published by the Free Software @@ -19,6 +19,27 @@ #ifndef __NX_WRITER_H__ #define __NX_WRITER_H__ +// ============================================================================ +//! \page highlevelPage High level NeXus API documentation +//! \tableofcontents +//! +//! \section secB1 High level NeXus writing API +//! The high level writing API provide classes allow writing large datasets in +//! synchronous or asynchonous mode +//! +//! \section secB2 High level NeXus writing classes +//! Links to classes : \n +//! - nxcpp::DatasetWriter +//! - nxcpp::GenericDatasetWriter +//! - nxcpp::AxisDatasetWriter +//! - nxcpp::SignalDatasetWriter +//! - nxcpp::NexusFileWriter +//! - nxcpp::MMetadata +//! - nxcpp::IExceptionHandler +//! - nxcpp::IMessageHandler +//! +// ============================================================================ + // standard library objets #include <iostream> #include <vector> @@ -49,7 +70,7 @@ void message_to_console(yat::ELogLevel lvl, const yat::String& msg); void exception_to_console(const yat::Exception& e); //============================================================================= -/// Mix-in that add metadata capabilitie to objects +//! Mix-in that add metadata capabilitie to objects //============================================================================= class MMetadata { @@ -70,118 +91,202 @@ private: std::map<std::string, double> m_mapDouble; // "Float" type metadata public: - /// Add std::string metadata + //! Add std::string metadata + //! + //! \param strKey metadata name + //! \param strValue metadata value void AddMetadata(const std::string &strKey, const std::string &strValue); - /// Add C-ansi std::string metadata + + //! Add C-ansi std::string metadata + //! + //! \param strKey metadata name + //! \param pszValue metadata value void AddMetadata(const std::string &strKey, const char *pszValue); - /// Add integer matedata + + //! Add integer matedata + //! + //! \param strKey metadata name + //! \param iValue metadata value void AddMetadata(const std::string &strKey, int iValue); - /// Add integer matedata + + //! Add integer matedata + //! + //! \param strKey metadata name + //! \param lValue metadata value void AddMetadata(const std::string &strKey, long lValue); - /// Add float metadata + + //! Add float metadata + //! + //! \param strKey metadata name + //! \param dValue metadata value void AddMetadata(const std::string &strKey, double dValue); - /// Check metadata + //! Check metadata + //! + //! \param strKey metadata name bool HasMetadata(const std::string &strKey) const; - /// Get metadata as std::string - /// Implicitely convert integer and float metadata as std::string value - /// @param bThrow if true throw a exception in case of no data - /// @return true if metadata was found, otherwise false (if bThrow == false) + //! Get metadata as std::string + //! Implicitely convert integer and float metadata as string value + //! + //! \param strKey metadata name + //! \param[out] pstrValue Value as string + //! \param bThrow if true throw a exception in case of no data + //! \return true if metadata was found, otherwise false (if bThrow == false) bool GetMetadata(const std::string &strKey, std::string *pstrValue, bool bThrow=true) const; - /// Get std::string metadata - /// @param bThrow if true throw a exception in case of no data - /// @return true if metadata was found, otherwise false (if bThrow == false) + //! Get string metadata + //! + //! \param strKey metadata name + //! \param[out] pstrValue pointer output value + //! \param bThrow if true throw a exception in case of no data + //! \return true if metadata was found, otherwise false (if bThrow == false) bool GetStringMetadata(const std::string &strKey, std::string *pstrValue, bool bThrow=true) const; + + //! Get string metadata + //! + //! \param strKey metadata name + //! \return metadata value + //! \throw Throw an exception if the key is not found std::string StringMetadata(const std::string &strKey) const; - /// Get integer metadata - /// @param bThrow if true throw a exception in case of no data - /// @return true if metadata was found, otherwise false (if bThrow == false) + //! Get integer metadata + //! + //! \param strKey metadata name + //! \param[out] piValue pointer output value + //! \param bThrow if true throw a exception in case of no data + //! \return true if metadata was found, otherwise false (if bThrow == false) bool GetIntegerMetadata(const std::string &strKey, int *piValue, bool bThrow=true) const; + + //! Get integer metadata + //! + //! \param strKey metadata name + //! \return metadata value + //! \throw Throw an exception if the key is not found int IntegerMetadata(const std::string &strKey) const; - /// Get long integer metadata - /// @param bThrow if true throw a exception in case of no data - /// @return true if metadata was found, otherwise false (if bThrow == false) + //! Get long integer metadata + //! + //! \param strKey metadata name + //! \param[out] plValue pointer output value + //! \param bThrow if true throw a exception in case of no data + //! \return true if metadata was found, otherwise false (if bThrow == false) bool GetLongIntegerMetadata(const std::string &strKey, long *plValue, bool bThrow=true) const; + + //! Get long integer metadata + //! + //! \param strKey metadata name + //! \return metadata value + //! \throw Throw an exception if the key is not found long LongIntegerMetadata(const std::string &strKey) const; - /// Get float metadata - /// @param bThrow if true throw a exception in case of no data - /// @return true if metadata was found, otherwise false (if bThrow == false) + //! Get long float (double-type) metadata + //! + //! \param strKey metadata name + //! \param[out] pdValue pointer output value + //! \param bThrow if true throw a exception in case of no data + //! \return true if metadata was found, otherwise false (if bThrow == false) bool GetDoubleMetadata(const std::string &strKey, double *pdValue, bool bThrow=true) const; + + //! Get long float (double-type) metadata + //! + //! \param strKey metadata name + //! \return metadata value + //! \throw Throw an exception if the key is not found double DoubleMetadata(const std::string &strKey) const; - /// Get type of a metadata from its key name - /// @param bThrow if true throw a exception in case of no data - /// @return MMetadata::Type value + //! Get type of a metadata from its key name + //! + //! \param strKey metadata name + //! \param bThrow if true throw a exception in case of no data + //! \return MMetadata::Type value Type GetMetadataType(const std::string &strKey, bool bThrow=true) const; - /// Returns the metadata keys std::list + //! Returns the metadata keys std::list std::list<std::string> MetadataKeys() const; - /// Clear all metadata + //! Clear all metadata void ClearMetadata(); }; //============================================================================= -/// Exception handling interface +//! Exception handling interface //============================================================================= class IExceptionHandler { public: + //! Method to implement virtual void OnNexusException(const NexusException &e)=0; }; //============================================================================= -/// Message handling interface +//! Message handling interface //============================================================================= class IMessageHandler { public: + //! Method to implement + //! + //! \param lvl log level as defined in the yat library + //! \param msg the message virtual void OnNexusMessage(yat::ELogLevel lvl, const yat::String& msg)=0; }; //============================================================================= -/// Synchronous/Asynchronous NeXus Writer File Class -/// -/// This class allow asynchronous writing into a nexus file -/// @note This is wrapper class, the real job is make by a internal objet +//! Synchronous/Asynchronous NeXus Writer File Class +//! +//! This class allow asynchronous writing into a nexus file +//! \remark This is wrapper class, the real job is make by a internal objet //============================================================================= class NEXUSCPP_DECL NexusFileWriter { public: enum WriteMode { - SYNCHRONOUS = 0, /// Synchronous mode - ASYNCHRONOUS, /// Asynchronous mode + SYNCHRONOUS = 0, //! Synchronous mode + ASYNCHRONOUS, //! Asynchronous mode ///@{ Depracated modes - IMMEDIATE, /// Asynchronous mode: write data as soon as possible - DELAYED /// Asynchronous mode: data are cached and written at specified time interval + IMMEDIATE, + DELAYED ///@} }; + //! Writing speed statistics typedef struct Statistics { Statistics(); yat::uint64 ui64WrittenBytes; yat::uint64 ui64TotalBytes; - float fInstantMbPerSec; /// Instant rate in MBytes/s - float fAverageMbPerSec; /// Average rate in MBytes/s + float fInstantMbPerSec; //! Instant rate in MBytes/s + float fAverageMbPerSec; //! Average rate in MBytes/s double dTotalWriteTime; } Statistics; //============================================================================= - /// Write notification interface + //! Write notification interface //============================================================================= class INotify { public: + //! Write subset notification + //! + //! \param[out] source_p object address who performed the write operation + //! \param[out] dataset_path Path to the written dataset + //! \param[out] start_pos start position of the subset + //! \param[out] dim subset dimensions array virtual void OnWriteSubSet(NexusFileWriter* source_p, const std::string& dataset_path, int start_pos[MAX_RANK], int dim[MAX_RANK])=0; + + //! Write whole dataset notification + //! + //! \param[out] source_p object address who performed the write operation + //! \param[out] dataset_path Path to the written dataset virtual void OnWrite(NexusFileWriter* source_p, const std::string& dataset_path)=0; + + //! File close notification + //! + //! \param[out] source_p object address who performed the write operation + //! \param[out] nexus_file_path Closed file path virtual void OnCloseFile(NexusFileWriter* source_p, const std::string& nexus_file_path)=0; }; @@ -192,117 +297,116 @@ private: static std::size_t s_attempt_delay_ms_; public: - /// Constructor - /// - /// @param strFilePath path + complete filename + //! Constructor + //! + //! \param strFilePath path + complete filename + //! \param eMode Writing mode + //! \param uiWritePeriod Write period (seconds) in asynchronous mode NexusFileWriter(const std::string &strFilePath, WriteMode eMode=ASYNCHRONOUS, unsigned int uiWritePeriod=2); - /// Destructor - /// + //! Destructor ~NexusFileWriter(); - /// Set exception handler - /// + //! Set exception handler void SetExceptionHandler(IExceptionHandler *pHandler); - /// Set message handler - /// + //! Set message handler void SetMessageHandler(IMessageHandler *pHandler); - /// Set the notification handler - /// + //! Set the notification handler void SetNotificationHandler(INotify *pHandler); - /// Set the notification handler - /// + //! Set the notification handler void AddNotificationHandler(INotify* pHandler); - /// Set cache size (in MB) for DELAYED mode - /// + //! Set cache size (in MB) for DELAYED mode void SetCacheSize(yat::uint16 usCacheSize); - /// Create a dataset - /// - /// @param strPath Dataset path and name (ex: entry<NXentry>/sample<NXsample>/formula) - /// @param aDataSet The dataset to write + //! Create a dataset + //! + //! \param strPath Dataset path and name (ex: "entry<NXentry>/sample<NXsample>/formula") + //! \param eDataType The data type + //! \param iRank number of dimensions + //! \param piDim dimensions array + //! \param filter Compression filter (no compression is the default) + //! \param filter_config Compression filter parameters + //! \param piChunk dimensions array of compress chunks (null if no compression) void CreateDataSet(const std::string &strPath, NexusDataType eDataType, int iRank, int *piDim, CompressionFilter filter=CompressNone, FilterConfig filter_config=FilterConfig(), int *piChunk=0); - /// Push a dataset - /// - /// @param strPath Dataset path and name (ex: entry<NXentry>/sample<NXsample>/formula) - /// @param aDataSet The dataset to write + //! Push a dataset + //! + //! \param strPath Dataset path and name (ex: "entry<NXentry>/sample<NXsample>/formula") + //! \param ptrDataSet Shared pointer to the dataset to push void PushDataSet(const std::string &strPath, NexusDataSetPtr ptrDataSet); - /// Push a attribute - /// Dataset must already exists, otherwise a error is repported and action is canceled - /// - /// @param strPath Dataset path and name (ex: entry<NXentry>/sample<NXsample>/formula.attribute) - /// @param aAttr The attribute - /// + //! Push a attribute + //! Dataset must already exists, otherwise a error is repported and action is canceled + //! + //! \param strPath Dataset path and name (ex: "entry<NXentry>/sample<NXsample>/formula.attribute") + //! \param ptrAttr Shared pointer to the attribute void PushDatasetAttr(const std::string &strPath, NexusAttrPtr ptrAttr); - /// Abort: delete all remaining data if any, no more access to file - /// When this method returns - /// + //! Abort: delete all remaining data if any, no more access to file + //! When this method returns void Abort(); - /// True + //! True bool IsError(); - /// Returns true if there is no data to write + //! Returns true if there is no data to write bool IsEmpty(); - /// Returns true when all job is done + //! Returns true when all job is done bool Done(); - /// Wait until all job is done + //! Wait until all job is done void Synchronize(bool bSendSyncMsg=true); - /// Hold the data, force the NeXuisFileWriter to cache data and not writting it into the filename - /// Until either Synchronize() or Hold(false) is calles - /// Available only in asynchronous mode + // Hold the data, force the NeXuisFileWriter to cache data and not writting it into the filename + // Until either Synchronize() or Hold(false) is calles + // Available only in asynchronous mode void Hold(bool b=true); - /// Return true if it hold the data - /// Make sense only in asynchronous mode + // Return true if it hold the data + // Make sense only in asynchronous mode bool IsHold() const; - /// File name + //! File name const std::string &File() const; - /// The file will not be closed after each write action + //! The file will not be closed after each write action void SetFileAutoClose(bool b); - /// Close the nexus file + //! Close the nexus file void CloseFile(); - /// Engage the file lock mecanism + //! Engage the file lock mecanism void SetUseLock(); //@{ Attempt values for retry mechanism - /// Max attempts for write actions + //! Max attempts for write actions static std::size_t AttemptMax() { return s_attempt_max_; } - /// delay (in ms) between to attempts + //! delay (in ms) between to attempts static std::size_t AttemptDelay() { return s_attempt_delay_ms_; } - /// set max attempts for write actions + //! set max attempts for write actions static void SetAttemptMax(std::size_t n); - /// set (in ms) between to attempts + //! set (in ms) between to attempts static void SetAttemptDelay(std::size_t ms); //@} //@{ Statistics - /// Reset all statistics + //! Reset all statistics void ResetStatistics(); - /// Gets a copy of the statistics + //! Gets a copy of the statistics Statistics GetStatistics() const; //@} @@ -310,19 +414,19 @@ public: typedef yat::MemBuf DatasetBuf; -// Referenced pointer definition +//! Referenced pointer definition typedef yat::SharedPtr<NexusFileWriter, yat::Mutex> NexusFileWriterPtr; -/// Data shape type +//! Data shape type typedef std::vector<std::size_t> DataShape; // Empty shape extern const DataShape g_empty_shape; //============================================================================== -/// DatasetWriter -/// -/// class containing a NexusDataset with its attributes and its location +//! DatasetWriter +//! +//! class containing a NexusDataset with its attributes and its location //============================================================================== class NEXUSCPP_DECL DatasetWriter:public MMetadata { @@ -333,17 +437,31 @@ public: virtual void OnFlushData(DatasetWriter* pWriter) = 0; }; + //! DatasetWriter configuration typedef struct Config { - /// + //! Dimensions array of canonical data DataShape shape_data_item; + + //! Dimensions array of acquisition space DataShape shape_matrix; + + //! Write cache size yat::uint16 cache_mb; + + //! useless parameter (to be deleted) yat::uint16 write_tmout; + + //! Compress filter CompressionFilter compress_filter; + + //! Compress filter parameters FilterConfig filter_config; + + //! minimal dataset size for compression, smaller datasets are not compressed std::size_t min_bytes_for_compression; + //! default c-tor Config() { compress_filter = CompressNone; @@ -385,82 +503,105 @@ private: void init(yat::uint16 usMaxMB, yat::uint16 m_usWriteTimeout); public: + //! Sets the NeXus dataset type according to the class invoked through the template template <class TYPE> void SetDataType(); + //! reset the writer in order to re-using it void Reset(); + //! Sets the NeXus dataset type void SetNeXusDataType(NexusDataType eDataType); + //! Set dataset shape + //! + //! \param shapeDataItem shape of the canonical data + //! \param shapeMatrix shape of the acquisition void SetShapes(const DataShape &shapeDataItem, const DataShape &shapeMatrix); + //! Set compression parameters void set_compression(CompressionFilter filter=CompressZLIB, FilterConfig filter_config=FilterConfig()); - /// c-tor + //! Main constructor + //! + //! \param shapeDataItem Shape of the canonical data + //! \param shapeMatrix Shape of the acquisition + //! \param usMaxMB Cache size + //! \param m_usWriteTimeout Max time before flushing cached data DatasetWriter(const DataShape &shapeDataItem, const DataShape &shapeMatrix=g_empty_shape, yat::uint16 usMaxMB=64, yat::uint16 m_usWriteTimeout=0); + + //! Convenience constructor for 1-D scan + //! + //! \param shapeDataItem Shape of the canonical data + //! \param one_dim_size Scan length + //! \param usMaxMB Cache size + //! \param m_usWriteTimeout Max time before flushing cached data DatasetWriter(const DataShape &shapeDataItem, std::size_t one_dim_size, yat::uint16 usMaxMB=64, yat::uint16 m_usWriteTimeout=0); + + //! Use this constructor when shapes are now known yet + //! + //! \param usMaxMB Cache size + //! \param m_usWriteTimeout Max time before flushing cached data DatasetWriter(yat::uint16 usMaxMB=64, yat::uint16 m_usWriteTimeout=0); DatasetWriter(const Config& cfg); - /// @deprecated - DatasetWriter(const std::vector<int>& shapeDataItem, const std::vector<int>& shapeMatrix, yat::uint16 usMaxMB=64); - DatasetWriter(const std::vector<int> &shapeDataItem, std::size_t one_dim_size, yat::uint16 usMaxMB=64); + //@{ Deprecated methods + DatasetWriter(const std::vector<int>&, const std::vector<int>&, yat::uint16 usMaxMB=64); + DatasetWriter(const std::vector<int>&, std::size_t, yat::uint16 usMaxMB=64); + //@} /// d-tor virtual ~DatasetWriter(); - /// Set Nexus file writer object - /// Must be called before push any data, like after construction or a call to the Stop method - /// - /// @param ptrWriter referenced pointer to the new writer object - /// + //! Set Nexus file writer object + //! Must be called before push any data, like after construction or a call to the Stop method + //! + //! \param ptrWriter referenced pointer to the new writer object void SetNexusFileWriter(NexusFileWriterPtr ptrWriter); - /// Set the flushing notification listener - /// Must be called before push any data, like after construction or a call to the Stop method - /// - /// @param ptrWriter referenced pointer to the new writer object - /// + //! Set the flushing notification listener + //! Must be called before push any data, like after construction or a call to the Stop method + //! + //! \param pListener pointer to the listener void SetFlushListener(IFlushNotification* pListener) { m_pFlushListener = pListener; } - /// Resizes matrix - /// Must be called before push any data, like after construction or a call to the Stop method - /// - /// @param shapeMatrix new shape - /// + //! Resizes matrix + //! Must be called before push any data, like after construction or a call to the Stop method + //! + //! \param shapeMatrix new shape void SetMatrix(const DataShape &shapeMatrix=g_empty_shape); - /// Change destination path + //! Change destination path void SetPath(const std::string &strPath, const std::string &strDataset); - /// Change destination path + //! Change destination path void SetFullPath(const std::string &strFullPath); - /// Set the dataset name + //! Set the dataset name void SetDatasetName(const std::string &strDatasetName); - /// Sets the buffer size in Mega bytes + //! Sets the buffer size in Mega bytes void SetCacheSize(yat::uint16 usMaxMB) { m_usMaxMB = usMaxMB; } - /// Adding integer-type attribute to the NeXus dataset + //! Adding integer-type attribute to the NeXus dataset void AddAttribute(const NexusAttrPtr &ptrAttr); - /// Adding double-type attribute to the NeXus dataset + //! Adding double-type attribute to the NeXus dataset void AddFloatAttribute(const std::string &strName, double dValue); - /// Adding integer-type attribute to the NeXus dataset + //! Adding integer-type attribute to the NeXus dataset void AddIntegerAttribute(const std::string &strName, long lValue); - /// Adding std::string-type attribute to the NeXus dataset + //! Adding std::string-type attribute to the NeXus dataset void AddStringAttribute(const std::string &strName, const std::string &strValue); - /// Push data + //! Push data void PushData(const void *pData, std::size_t nDataCount=1, bool bNoCopy=false); - /// No more data to push, data is flushed to the NeXus file writer + //! No more data to push, data is flushed to the NeXus file writer void Stop(); - /// Cancel => forget all + //! Cancel => forget all void Abort(); //@{ Accessors @@ -477,59 +618,71 @@ public: //@} }; -// Referenced pointer definition +//! Shared pointer definition typedef yat::SharedPtr<DatasetWriter, yat::Mutex> DatasetWriterPtr; //============================================================================== -/// GenericDatasetWriter -/// -/// class containing a NexusDataset with its attributes and its location +//! GenericDatasetWriter +//! +//! Typed DatasetWriter class //============================================================================== template <class TYPE> class GenericDatasetWriter: public DatasetWriter { public: - /// c-tor + //! c-tor + //! \param shapeDataItem Shape of the canonical data + //! \param shapeMatrix Shape of the acquisition + //! \param usMaxMB Cache size GenericDatasetWriter(const DataShape &shapeDataItem, const DataShape &shapeMatrix=g_empty_shape, unsigned short usMaxMB=100); - /// d-tor + //! d-tor ~GenericDatasetWriter() {} - }; //============================================================================== -/// AxisDatasetWriter -/// -/// class containing a NexusDataset with its attributes and its location +//! AxisDatasetWriter +//! +//! Typed DatasetWriter class dedicated to for axis data //============================================================================== template <class TYPE> class AxisDatasetWriter: public DatasetWriter { public: - /// c-tor + //! c-tor + //! \param iDim Dimension number of axis + //! \param iSize Dimension length + //! \param iOrder Axis order in the dimension AxisDatasetWriter(int iDim, int iSize, int iOrder=1); - /// d-tor + //! d-tor ~AxisDatasetWriter() {} void PushPosition(TYPE TValue); }; //============================================================================== -/// SignalDatasetWriter -/// -/// class containing a NexusDataset with its attributes and its location +//! SignalDatasetWriter +//! +//! class containing a NexusDataset with its attributes and its location +//! Typed DatasetWriter class dedicated to for signal data //============================================================================== template <class TYPE> class SignalDatasetWriter: public DatasetWriter { public: - /// c-tor + //! c-tor + //! \param shapeData Shape of the canonical data + //! \param shapeMatrix Shape of the acquisition + //! \param iSignal axis order in the dimension SignalDatasetWriter(const DataShape &shapeData, const DataShape &shapeMatrix=g_empty_shape, int iSignal=1); - /// d-tor + //! d-tor ~SignalDatasetWriter() {} + //! Push one position + //! + //! \param pValue pointer to the position value void PushSignal(TYPE *pValue); }; diff --git a/licence.txt b/licence.txt new file mode 100644 index 0000000..65c5ca8 --- /dev/null +++ b/licence.txt @@ -0,0 +1,165 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + + This version of the GNU Lesser General Public License incorporates +the terms and conditions of version 3 of the GNU General Public +License, supplemented by the additional permissions listed below. + + 0. Additional Definitions. + + As used herein, "this License" refers to version 3 of the GNU Lesser +General Public License, and the "GNU GPL" refers to version 3 of the GNU +General Public License. + + "The Library" refers to a covered work governed by this License, +other than an Application or a Combined Work as defined below. + + An "Application" is any work that makes use of an interface provided +by the Library, but which is not otherwise based on the Library. +Defining a subclass of a class defined by the Library is deemed a mode +of using an interface provided by the Library. + + A "Combined Work" is a work produced by combining or linking an +Application with the Library. The particular version of the Library +with which the Combined Work was made is also called the "Linked +Version". + + The "Minimal Corresponding Source" for a Combined Work means the +Corresponding Source for the Combined Work, excluding any source code +for portions of the Combined Work that, considered in isolation, are +based on the Application, and not on the Linked Version. + + The "Corresponding Application Code" for a Combined Work means the +object code and/or source code for the Application, including any data +and utility programs needed for reproducing the Combined Work from the +Application, but excluding the System Libraries of the Combined Work. + + 1. Exception to Section 3 of the GNU GPL. + + You may convey a covered work under sections 3 and 4 of this License +without being bound by section 3 of the GNU GPL. + + 2. Conveying Modified Versions. + + If you modify a copy of the Library, and, in your modifications, a +facility refers to a function or data to be supplied by an Application +that uses the facility (other than as an argument passed when the +facility is invoked), then you may convey a copy of the modified +version: + + a) under this License, provided that you make a good faith effort to + ensure that, in the event an Application does not supply the + function or data, the facility still operates, and performs + whatever part of its purpose remains meaningful, or + + b) under the GNU GPL, with none of the additional permissions of + this License applicable to that copy. + + 3. Object Code Incorporating Material from Library Header Files. + + The object code form of an Application may incorporate material from +a header file that is part of the Library. You may convey such object +code under terms of your choice, provided that, if the incorporated +material is not limited to numerical parameters, data structure +layouts and accessors, or small macros, inline functions and templates +(ten or fewer lines in length), you do both of the following: + + a) Give prominent notice with each copy of the object code that the + Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the object code with a copy of the GNU GPL and this license + document. + + 4. Combined Works. + + You may convey a Combined Work under terms of your choice that, +taken together, effectively do not restrict modification of the +portions of the Library contained in the Combined Work and reverse +engineering for debugging such modifications, if you also do each of +the following: + + a) Give prominent notice with each copy of the Combined Work that + the Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the Combined Work with a copy of the GNU GPL and this license + document. + + c) For a Combined Work that displays copyright notices during + execution, include the copyright notice for the Library among + these notices, as well as a reference directing the user to the + copies of the GNU GPL and this license document. + + d) Do one of the following: + + 0) Convey the Minimal Corresponding Source under the terms of this + License, and the Corresponding Application Code in a form + suitable for, and under terms that permit, the user to + recombine or relink the Application with a modified version of + the Linked Version to produce a modified Combined Work, in the + manner specified by section 6 of the GNU GPL for conveying + Corresponding Source. + + 1) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (a) uses at run time + a copy of the Library already present on the user's computer + system, and (b) will operate properly with a modified version + of the Library that is interface-compatible with the Linked + Version. + + e) Provide Installation Information, but only if you would otherwise + be required to provide such information under section 6 of the + GNU GPL, and only to the extent that such information is + necessary to install and execute a modified version of the + Combined Work produced by recombining or relinking the + Application with a modified version of the Linked Version. (If + you use option 4d0, the Installation Information must accompany + the Minimal Corresponding Source and Corresponding Application + Code. If you use option 4d1, you must provide the Installation + Information in the manner specified by section 6 of the GNU GPL + for conveying Corresponding Source.) + + 5. Combined Libraries. + + You may place library facilities that are a work based on the +Library side by side in a single library together with other library +facilities that are not Applications and are not covered by this +License, and convey such a combined library under terms of your +choice, if you do both of the following: + + a) Accompany the combined library with a copy of the same work based + on the Library, uncombined with any other library facilities, + conveyed under the terms of this License. + + b) Give prominent notice with the combined library that part of it + is a work based on the Library, and explaining where to find the + accompanying uncombined form of the same work. + + 6. Revised Versions of the GNU Lesser General Public License. + + The Free Software Foundation may publish revised and/or new versions +of the GNU Lesser General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the +Library as you received it specifies that a certain numbered version +of the GNU Lesser General Public License "or any later version" +applies to it, you have the option of following the terms and +conditions either of that published version or of any later version +published by the Free Software Foundation. If the Library as you +received it does not specify a version number of the GNU Lesser +General Public License, you may choose any version of the GNU Lesser +General Public License ever published by the Free Software Foundation. + + If the Library as you received it specifies that a proxy can decide +whether future versions of the GNU Lesser General Public License shall +apply, that proxy's public statement of acceptance of any version is +permanent authorization for you to choose that version for the +Library. diff --git a/src/nxhdf5.cpp b/src/nxhdf5.cpp index 4636cf3..bfc5f02 100755 --- a/src/nxhdf5.cpp +++ b/src/nxhdf5.cpp @@ -4,7 +4,7 @@ /// NeXus C++ API /// /// Creation : 16/02/2005 -/// Author : Stephane Poirier +/// Authors : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud /// /// This program is free software; you can redistribute it and/or modify it under /// the terms of the GNU General Public License as published by the Free Software diff --git a/src/nxwriter.cpp b/src/nxwriter.cpp index d33621f..49212e3 100644 --- a/src/nxwriter.cpp +++ b/src/nxwriter.cpp @@ -1514,6 +1514,7 @@ void NexusFileWriter::Synchronize(bool bSendSyncMsg) if( NexusFileWriter::SYNCHRONOUS != m_pImpl->WriteMode() ) { + //## clarifier if( NexusFileWriter::DELAYED == m_pImpl->WriteMode() ) { m_pImpl->post(new yat::Message(NexusFileWriterImpl::PROCESS_CACHE)); -- GitLab