OpenSCADAWiki: Home Page En/Doc/API/part16 ...

16. Resources in the OpenSCADA system (Res, ResAlloc, AutoHD)

Most of the units and subsystems of the OpenSCADA are dynamic, ie they allow the creation/deletion/configuration while the system is working. Taking into account the multi-threading of the system, this functionality imposes stringent requirements for synchronization of threads. For synchronization in the system the resources are used, functions of which are localized in the objects "Res" and "ResAlloc". Object "Res" provides storage of the resource, providing the functions of capture/release for the read and write. In object "ResAlloc" the automatic release of the resource functions are implemented. Automatic resource involves the creation of a local resource object with its automatic release at fracture (in the destructor). Using of automatic resource makes the work with resources when using the exceptions much easier.

Any dynamic system object is inherited from "TCntrNode" object, which contains a mechanism to connect via the "AutoHD" template. The main function of the template is to store the link to the object and the capture of the resource, excluding the deleting of the object at the time of use. Template supports copying the resource and its release in case of destruction of the template object. For clarity of the access to the objects generated by "TCntrNode" the "AutoHD" template supports casting, based on the dynamic cast.

16.1. Resource R/W lock object (Res)

Public methods:

• Res( ); — Initialization of the resource.
• static void resRequestW( long tm = 0 ); — Request the resource for writing/modification with wait timeout tm (in milliseconds).
• bool resTryW( ); — Request try the resource for writing/modification. On success return "true" else "false".
• static void resRequestR( long tm = 0 ); — Request the resource for reading with wait timeout tm (in milliseconds).
• bool resTryR( ); — Request try the resource for reading. On success return "true" else "false".
• static void resRelease( ); — Release of the resource.

16.2. Automatic resource RW unlock object (ResAlloc)

Public methods:

• ResAlloc( Res &rid ); — Initialization of the automatically released resource for the previously selected identifier rid.
• ResAlloc( Res &rid, bool write, long tm = 0 ); — Initialization of the automatically released resource for the previously selected identifier rid. With the specification of the resource type write (read/write).
• void request( bool write = false, long tm = 0 ); void lock( bool write = false, unsigned short tm = 0 ); — Request of the resource in the specified mode write (read/write).
• void release( ); void unlock( ); — Release of the resource.

16.3. Template (AutoHD)

Public methods:

• AutoHD( ); — Initializing without linkage to the object.
• AutoHD( ORes *node, const string &who = "" ); — Initialization with the linkage to the object node. The object must contain the function AHDConnect() and AHDDisConnect().
• AutoHD( const AutoHD &hd ); — Copyng constructor.
• template <class ORes1> AutoHD( const AutoHD<ORes1> &hd_s, bool nosafe = false ); — Ñast constructor in safe mode casting (by help dynamic_cast). Return free resource on impossible cast.
• ORes &at( ) const; — Getting the object by the resource.
• AutoHD &operator=(const AutoHD &hd); — Copying of the resources.
• bool operator==(const AutoHD &hd); — Compare objects into resource by pointer.
• void free( ); — Release of the resource.
• bool freeStat( ) const; — The sign «The resource is free».

16.4. Object of the string with the access shared by the resource (ResString)

Public methods:

• explicit ResString( const string &vl = "" ); — Initialization of the string with the specified value vl.
• ResString &operator=( const string &val ); — Function for implicit conversion from std::string.
• operator string( ); — Function for implicit conversion to std::string.
• size_t size( ); — The string size.
• bool empty( ); — The string empty.
• void setVal( const string &vl ); — Setting the string's value to vl.
• const string &getVal( ); — Getting the string's value.
• const string &getValRef( ); — Getting a direct reference to the string std::string. The resource is ignored when you use this function!

16.5. Object of automatic unlock POSIX mutex (MtxAlloc)

Public methods:

• MtxAlloc( pthread_mutex_t &iM, bool lock = false ); — Initialization of automatic unlock mutex for early allocated identifier iM. With the lock lock set at creation.
• void lock( ); — The resource lock. Return zero at success.
• void unlock( ); — The resource unlock. Return zero at success.
• int tryLock( ); — The resource try lock, without wait for free. Return zero at success.

16.6. Object of the string with the access shared by the global the data resource (mutex) (MtxString)

Public methods:

• MtxString( pthread_mutex_t &iM ); — The string initialization with the access sharing by resource iM.
• MtxString &operator=( const string &val ); — Function for implicit conversion from std::string.
• operator string( ); — Function for implicit conversion to std::string.
• size_t size( ); — The string size.
• bool empty( ); — The string empty.
• void setVal( const string &vl ); — Setting the string's value to vl.
• const string &getVal( ); — Getting the string's value.
• const string &getValRef( ); — Getting a direct reference to the string std::string. The resource is ignored when you use this function!