mainly doc changes

This commit is contained in:
mrkraimer
2016-07-18 13:01:35 -04:00
parent 1d80fbf512
commit 03fc6f4a63
9 changed files with 314 additions and 1056 deletions

View File

@@ -67,15 +67,16 @@ class epicsShareClass MonitorFactory
public:
POINTER_DEFINITIONS(MonitorFactory);
/**
* Destructor
* @brief Destructor
*/
virtual ~MonitorFactory();
/**
* Destroy the monitor factory.
* @brief Destroy the monitor factory.
*/
virtual void destroy();
/**
* Create a monitor on a record.
* @brief Create a monitor on a record.
*
* This is called by the local channel provider.
* @param pvRecord The record to monitor.
* @param monitorRequester The client callback.
@@ -113,21 +114,22 @@ class epicsShareClass ChannelProviderLocal :
public:
POINTER_DEFINITIONS(ChannelProviderLocal);
/**
* Destructor
* @brief Destructor
*/
virtual ~ChannelProviderLocal();
/**
* Destroy the channel provider.
* @brief Destroy the channel provider.
*
* Probably never called.
*/
virtual void destroy();
/**
* Returns the channel provider name.
* @brief Returns the channel provider name.
* @return <b>local</b>
*/
virtual std::string getProviderName();
/**
* Returns either a null channelFind or a channelFind for records in the PVDatabase.
* @brief Returns either a null channelFind or a channelFind for records in the PVDatabase.
* @param channelName The name of the channel desired.
* @param channelFindRequester The client callback.
* @return shared pointer to ChannelFind.
@@ -142,8 +144,9 @@ public:
std::string const &channelName,
epics::pvAccess::ChannelFindRequester::shared_pointer const & channelFindRequester);
/**
* Calls method channelListRequester::channelListResult which provides the
* caller with a list of the record names on the PVDatabase.
* @brief Calls method channelListRequester::channelListResult.
*
* This provides the caller with a list of the record names on the PVDatabase.
* A record name is the same as a channel name.
* @param channelListRequester The client callback.
* @return shared pointer to ChannelFind.
@@ -152,7 +155,8 @@ public:
virtual epics::pvAccess::ChannelFind::shared_pointer channelList(
epics::pvAccess::ChannelListRequester::shared_pointer const & channelListRequester);
/**
* Create a channel for a record.
* @brief Create a channel for a record.
*
* This method just calls the next method with a address of "".
* @param channelName The name of the channel desired.
* @param channelRequester The client callback.
@@ -164,7 +168,7 @@ public:
epics::pvAccess::ChannelRequester::shared_pointer const &channelRequester,
short priority);
/**
* Create a channel for a record.
* @brief Create a channel for a record.
* @param channelName The name of the channel desired.
* @param channelRequester The callback to call with the result.
* @param priority The priority.
@@ -219,11 +223,12 @@ public:
PVRecordPtr const & pvRecord
);
/**
* Destructor
* @brief Destructor
*/
virtual ~ChannelLocal();
/**
* Destroy the channel.
* @brief Destroy the channel.
*
* It cleans up all resources used to access the record.
* Note that this assumes that client has destroyed any objects that
* have been created for the channel like channelGet, etc.
@@ -231,18 +236,20 @@ public:
*/
virtual void destroy();
/**
* @brief Detach from the record.
*
* This is called when a record is being removed from the database.
* Calls destroy.
* @param pvRecord The record being destroyed.
*/
virtual void detach(PVRecordPtr const &pvRecord);
/**
* Get the requester name.
* @brief Get the requester name.
* @return returns the name of the channel requester.
*/
virtual std::string getRequesterName();
/**
* Passes the message to the channel requester.
* @brief Passes the message to the channel requester.
* @param message The message.
* @param messageType The message type.
*/
@@ -250,7 +257,7 @@ public:
std::string const & message,
epics::pvData::MessageType messageType);
/**
* Get the channel provider
* @brief Get the channel provider
* @return The provider.
*/
virtual epics::pvAccess::ChannelProvider::shared_pointer getProvider()
@@ -258,7 +265,7 @@ public:
return provider;
}
/**
* Get the remote address
* @brief Get the remote address
* @return <b>local</b>
*/
virtual std::string getRemoteAddress();
@@ -268,22 +275,23 @@ public:
*/
virtual epics::pvAccess::Channel::ConnectionState getConnectionState();
/**
* Get the channel name.
* @brief Get the channel name.
* @return the record name.
*/
virtual std::string getChannelName();
/**
* Get the channel requester
* @brief Get the channel requester
* @return The channel requester.
*/
virtual epics::pvAccess::ChannelRequester::shared_pointer getChannelRequester();
/**
* Is the channel connected?
* @return true
* @brief Is the channel connected?
* @return true.
*/
virtual bool isConnected();
/**
* Get the introspection interface for subField.
* @brief Get the introspection interface for subField.
*
* The introspection interface is given via GetFieldRequester::getDone.
* @param requester The client callback.
* @param subField The subField of the record.
@@ -301,8 +309,8 @@ public:
virtual epics::pvAccess::AccessRights getAccessRights(
epics::pvData::PVField::shared_pointer const &pvField);
/**
* Create a channelProcess.
* See pvAccess.html for details.
* @brief Create a channelProcess.
*
* @param requester The client callback.
* @param pvRequest The options specified by the client.
* @return A shared pointer to the newly created implementation.
@@ -312,8 +320,8 @@ public:
epics::pvAccess::ChannelProcessRequester::shared_pointer const &requester,
epics::pvData::PVStructurePtr const &pvRequest);
/**
* Create a channelGet.
* See pvAccess.html for details.
* @brief Create a channelGet.
*
* @param requester The client callback.
* @param pvRequest The options specified by the client.
* @return A shared pointer to the newly created implementation.
@@ -323,8 +331,8 @@ public:
epics::pvAccess::ChannelGetRequester::shared_pointer const &requester,
epics::pvData::PVStructurePtr const &pvRequest);
/**
* Create a channelPut.
* See pvAccess.html for details.
* @brief Create a channelPut.
*
* @param requester The client callback.
* @param pvRequest The options specified by the client.
* @return A shared pointer to the newly created implementation.
@@ -334,8 +342,8 @@ public:
epics::pvAccess::ChannelPutRequester::shared_pointer const &requester,
epics::pvData::PVStructurePtr const &pvRequest);
/**
* Create a channelPutGet.
* See pvAccess.html for details.
* @brief Create a channelPutGet.
*
* @param requester The client callback.
* @param pvRequest The options specified by the client.
* @return A shared pointer to the newly created implementation.
@@ -345,10 +353,9 @@ public:
epics::pvAccess::ChannelPutGetRequester::shared_pointer const &requester,
epics::pvData::PVStructurePtr const &pvRequest);
/**
* Create a channelRPC.
* This is not implemented because pvAccessCPP implements channelRPC.
* The server side of remote pvAccess implements a channel provider
* just for channelRPC.
* @brief Create a channelRPC.
*
* The PVRecord must implement <b>getService</b> or an empty shared pointer is returned.
* @param requester The client callback
* @param pvRequest The options specified by the client.
* @return null.
@@ -357,8 +364,8 @@ public:
epics::pvAccess::ChannelRPCRequester::shared_pointer const &requester,
epics::pvData::PVStructurePtr const &pvRequest);
/**
* Create a monitor.
* See pvAccess.html for details.
* @brief Create a monitor.
*
* @param requester The client callback.
* @param pvRequest The options specified by the client.
* @return A shared pointer to the newly created implementation.
@@ -368,8 +375,8 @@ public:
epics::pvData::MonitorRequester::shared_pointer const &requester,
epics::pvData::PVStructurePtr const &pvRequest);
/**
* Create a channelArray.
* See pvAccess.html for details.
* @brief Create a channelArray.
*
* @param requester The client callback.
* @param pvRequest The options specified by the client.
* @return A shared pointer to the newly created implementation.
@@ -379,12 +386,12 @@ public:
epics::pvAccess::ChannelArrayRequester::shared_pointer const &requester,
epics::pvData::PVStructurePtr const &pvRequest);
/**
* calls printInfo(std::cout);
* @brief calls printInfo(std::cout);
*/
virtual void printInfo();
/**
* displays a message
* "ChannelLocal provides access to a record in the local PVDatabase".
* @brief displays a message
*
* @param out the stream on which the message is displayed.
*/
virtual void printInfo(std::ostream& out);

View File

@@ -1,13 +1,8 @@
/* pvDatabase.h */
/**
* Copyright - See the COPYRIGHT that is included with this distribution.
* EPICS pvData is distributed subject to a Software License Agreement found
* in file LICENSE that is included with this distribution.
*/
/**
* @author mrk
* @date 2012.11.20
*/
#ifndef PVDATABASE_H
#define PVDATABASE_H
@@ -60,9 +55,13 @@ class PVDatabase;
typedef std::tr1::shared_ptr<PVDatabase> PVDatabasePtr;
/**
* @brief Base interface for a record.
* @brief Base interface for a PVRecord.
*
* It is also a complete implementation for <b>soft</b> records.
* A soft record is a record where method <b>process</b> sets an
* optional top level timeStamp field to the current time and does nothing else.
* @author mrk
* @date 2012.11.20
*/
class epicsShareClass PVRecord :
public epics::pvData::PVCopyTraverseMasterCallback,
@@ -75,19 +74,21 @@ public:
*/
virtual ~PVRecord();
/**
* Virtual initialization method.
* Must be implemented by derived classes.
* This method <b>Must</b> call initPVRecord.
* @brief Optional initialization method.
*
* A derived method <b>Must</b> call initPVRecord.
* @return <b>true</b> for success and <b>false</b> for failure.
*/
virtual bool init() {initPVRecord(); return true;}
/**
* Optional method for derived class.
* @brief Optional method for derived class.
*
* It is called before record is added to database.
*/
virtual void start() {}
/**
* Optional method.
* @brief Optional method for derived class.
*
* It is the method that makes a record smart.
* If it encounters errors it should raise alarms and/or
* call the <b>message</b> method provided by the base class.
@@ -96,106 +97,17 @@ public:
*/
virtual void process();
/**
* Destroy the PVRecord. Release any resources used and
* @brief Optional method for derived class.
*
* Destroy the PVRecord. Release any resources used and
* get rid of listeners and requesters.
* If derived class overrides this then it must call PVRecord::destroy()
* after it has destroyed any resorces it uses.
*/
virtual void destroy();
/**
* Creates a <b>soft</b> record.
* @param recordName The name of the record, which is also the channelName.
* @param pvStructure The top level structure.
* @return A shared pointer to the newly created record.
*/
static PVRecordPtr create(
std::string const & recordName,
epics::pvData::PVStructurePtr const & pvStructure);
/**
* Get the name of the record.
* @return The name.
*/
std::string getRecordName() const { return recordName;}
/**
* Get the top level PVRecordStructure.
* @return The shared pointer.
*/
PVRecordStructurePtr getPVRecordStructure() const { return pvRecordStructure;}
/**
* Convenience method for derived classes.
* @return The top level PVStructure.
*/
epics::pvData::PVStructurePtr getPVStructure() const { return pvStructure;}
/**
* Find the PVRecordField for the PVField.
* @param pvField The PVField.
* @return The shared pointer to the PVRecordField.
*/
PVRecordFieldPtr findPVRecordField(
epics::pvData::PVFieldPtr const & pvField);
/**
* Lock the record.
* Any code must lock while accessing a record.
*/
void lock();
/**
* Unlock the record.
*/
void unlock();
/**
* If <b>true</b> then just like <b>lock</b>.
* If <b>false</b>client can not access record.
* Code can try to simultaneously hold the lock for more than two records
* by calling this method but must be willing to accept failure.
* @return <b>true</b> if the record is locked.
*/
bool tryLock();
/**
* A client that holds the lock for one record can lock one other record.
* A client <b>must</b> not call this if the client already has the lock for
* more then one record.
* @brief Optional method for derived class.
*
* @param otherRecord The other record to lock.
*/
void lockOtherRecord(PVRecordPtr const & otherRecord);
/**
* Every client that accesses the record must call this so that the
* client can be notified when the record is deleted.
* @param pvRecordClient The client.
* @return <b>true</b> if the client is added.
*/
bool addPVRecordClient(PVRecordClientPtr const & pvRecordClient);
/**
* Remove a client.
* @param pvRecordClient The client.
* @return <b>true</b> if the client is removed.
*/
bool removePVRecordClient(PVRecordClientPtr const & pvRecordClient);
/**
* Add a PVListener.
* This must be called before calling pvRecordField.addListener.
* @param pvListener The listener.
* @param pvCopy The pvStructure that has the client fields.
* @return <b>true</b> if the listener was added.
*/
bool addListener(
PVListenerPtr const & pvListener,
epics::pvData::PVCopyPtr const & pvCopy);
/*
* PVCopyTraverseMasterCallback method
* @param pvField The next client field.
*/
void nextMasterPVField(epics::pvData::PVFieldPtr const & pvField);
/**
* Remove a listener.
* @param pvListener The listener.
* @param pvCopy The pvStructure that has the client fields.
* @return <b>true</b> if the listener was removed.
*/
bool removeListener(
PVListenerPtr const & pvListener,
epics::pvData::PVCopyPtr const & pvCopy);
/**
* Return a service corresponding to the specified request PVStructure.
* @param pvRequest The request PVStructure
* @return The corresponding service
@@ -205,28 +117,141 @@ public:
{
return epics::pvAccess::Service::shared_pointer();
}
/**
* @brief Creates a <b>soft</b> record.
*
* @param recordName The name of the record, which is also the channelName.
* @param pvStructure The top level structure.
* @return A shared pointer to the newly created record.
*/
static PVRecordPtr create(
std::string const & recordName,
epics::pvData::PVStructurePtr const & pvStructure);
/**
* @brief Get the name of the record.
*
* @return The name.
*/
std::string getRecordName() const { return recordName;}
/**
* @brief Get the top level PVRecordStructure.
*
* @return The shared pointer.
*/
PVRecordStructurePtr getPVRecordStructure() const { return pvRecordStructure;}
/**
* @brief Get the top level PVStructure.
*
* @return The top level PVStructure.
*/
epics::pvData::PVStructurePtr getPVStructure() const { return pvStructure;}
/**
* @brief Find the PVRecordField for the PVField.
*
* This is called by the pvCopy facility.
* @param pvField The PVField.
* @return The shared pointer to the PVRecordField.
*/
PVRecordFieldPtr findPVRecordField(
epics::pvData::PVFieldPtr const & pvField);
/**
* @brief Lock the record.
*
* Any code must lock while accessing a record.
*/
void lock();
/**
* @brief Unlock the record.
*
* The code that calls lock must unlock when done accessing the record.
*/
void unlock();
/**
* @brief Try to lock the record.
*
* If <b>true</b> then just like <b>lock</b>.
* If <b>false</b>client can not access record.
* Code can try to simultaneously hold the lock for more than two records
* by calling this method but must be willing to accept failure.
* @return <b>true</b> if the record is locked.
*/
bool tryLock();
/**
* @brief Lock another record.
*
* A client that holds the lock for one record can lock one other record.
* A client <b>must</b> not call this if the client already has the lock for
* more then one record.
*
* @param otherRecord The other record to lock.
*/
void lockOtherRecord(PVRecordPtr const & otherRecord);
/**
* @brief Add a client that wants to access the record.
*
* Every client that accesses the record must call this so that the
* client can be notified when the record is deleted.
* @param pvRecordClient The client.
* @return <b>true</b> if the client is added.
*/
bool addPVRecordClient(PVRecordClientPtr const & pvRecordClient);
/**
* @brief Remove a client.
*
* @param pvRecordClient The client.
* @return <b>true</b> if the client is removed.
*/
bool removePVRecordClient(PVRecordClientPtr const & pvRecordClient);
/**
* @brief Add a PVListener.
*
* This must be called before calling pvRecordField.addListener.
* @param pvListener The listener.
* @param pvCopy The pvStructure that has the client fields.
* @return <b>true</b> if the listener was added.
*/
bool addListener(
PVListenerPtr const & pvListener,
epics::pvData::PVCopyPtr const & pvCopy);
/**
* @brief PVCopyTraverseMasterCallback method
*
* @param pvField The next client field.
*/
void nextMasterPVField(epics::pvData::PVFieldPtr const & pvField);
/**
* @brief Remove a listener.
*
* @param pvListener The listener.
* @param pvCopy The pvStructure that has the client fields.
* @return <b>true</b> if the listener was removed.
*/
bool removeListener(
PVListenerPtr const & pvListener,
epics::pvData::PVCopyPtr const & pvCopy);
/**
* Begins a group of puts.
* @brief Begins a group of puts.
*/
void beginGroupPut();
/**
* Ends a group of puts.
* @brief Ends a group of puts.
*/
void endGroupPut();
/**
* get trace level (0,1,2) means (nothing,lifetime,process)
* @brief get trace level (0,1,2) means (nothing,lifetime,process)
* @return the level
*/
int getTraceLevel() {return traceLevel;}
/**
* set trace level (0,1,2) means (nothing,lifetime,process)
* @brief set trace level (0,1,2) means (nothing,lifetime,process)
* @param level The level
*/
void setTraceLevel(int level) {traceLevel = level;}
protected:
/**
* Constructor
* @brief Constructor
* @param recordName The name of the record
* @param pvStructure The top level PVStructutre
*/
@@ -234,10 +259,13 @@ protected:
std::string const & recordName,
epics::pvData::PVStructurePtr const & pvStructure);
/**
* Initializes the base class. Must be called by derived classes.
* @brief Initializes the base class.
*
* Must be called by derived classes.
*/
void initPVRecord();
/** Get shared pointer to self
/**
* @brief Get shared pointer to self.
* @return The shared pointer.
*/
PVRecordPtr getPtrSelf()
@@ -282,7 +310,8 @@ class epicsShareClass PVRecordField :
public:
POINTER_DEFINITIONS(PVRecordField);
/**
* Constructor.
* @brief Constructor.
*
* @param pvField The field from the top level structure.
* @param parent The parent.
* @param pvRecord The PVRecord.
@@ -292,36 +321,38 @@ public:
PVRecordStructurePtr const &parent,
PVRecordPtr const & pvRecord);
/**
* Destructor.
* @brief Destructor.
*/
virtual ~PVRecordField() {}
/**
* Get the parent.
* @brief Get the parent.
*
* @return The parent.
*/
PVRecordStructurePtr getParent();
/**
* Get the PVField.
* @brief Get the PVField.
*
* @return The shared pointer.
*/
epics::pvData::PVFieldPtr getPVField();
/**
* Get the full name of the field, i.e. field,field,..
* @brief Get the full name of the field, i.e. field,field,..
* @return The full name.
*/
std::string getFullFieldName();
/**
* Get the recordName plus the full name of the field, i.e. recordName.field,field,..
* @brief Get the recordName plus the full name of the field, i.e. recordName.field,field,..
* @return The name.
*/
std::string getFullName();
/**
* Returns the PVRecord to which this field belongs.
* @brief Return the PVRecord to which this field belongs.
* @return The shared pointer,
*/
PVRecordPtr getPVRecord();
/**
* This is called by the code that implements the data interface.
* @brief This is called by the code that implements the data interface.
* It is called whenever the put method is called.
*/
virtual void postPut();
@@ -355,7 +386,7 @@ class epicsShareClass PVRecordStructure : public PVRecordField {
public:
POINTER_DEFINITIONS(PVRecordStructure);
/**
* Constructor.
* @brief Constructor.
* @param pvStructure The data.
* @param parent The parent
* @param pvRecord The record that has this field.
@@ -365,22 +396,22 @@ public:
PVRecordStructurePtr const &parent,
PVRecordPtr const & pvRecord);
/**
* Destructor.
* @brief Destructor.
*/
virtual ~PVRecordStructure() {}
/**
* Get the sub fields.
* @brief Get the sub fields.
* @return the array of PVRecordFieldPtr.
*/
PVRecordFieldPtrArrayPtr getPVRecordFields();
/**
* Get the data structure/
* @brief Get the data structure/
* @return The shared pointer.
*/
epics::pvData::PVStructurePtr getPVStructure();
protected:
/**
* Called by implementation code of PVRecord.
* @brief Called by implementation code of PVRecord.
*/
virtual void init();
private:
@@ -398,11 +429,11 @@ class epicsShareClass PVRecordClient {
public:
POINTER_DEFINITIONS(PVRecordClient);
/**
* Destructor.
* @brief Destructor.
*/
virtual ~PVRecordClient() {}
/**
* Detach from the record because it is being removed.
* @brief Detach from the record because it is being removed.
* @param pvRecord The record.
*/
virtual void detach(PVRecordPtr const & pvRecord) = 0;
@@ -420,17 +451,19 @@ class epicsShareClass PVListener :
public:
POINTER_DEFINITIONS(PVListener);
/**
* Destructor.
* @brief Destructor.
*/
virtual ~PVListener() {}
/**
* pvField has been modified.
* @brief pvField has been modified.
*
* This is called if the listener has called PVRecordField::addListener for pvRecordField.
* @param pvRecordField The modified field.
*/
virtual void dataPut(PVRecordFieldPtr const & pvRecordField) = 0;
/**
* A subfield has been modified.
* @brief A subfield has been modified.
*
* @param requested The structure that was requested.
* @param pvRecordField The field that was modified.
*/
@@ -438,17 +471,17 @@ public:
PVRecordStructurePtr const & requested,
PVRecordFieldPtr const & pvRecordField) = 0;
/**
* Begin a set of puts.
* @brief Begin a set of puts.
* @param pvRecord The record.
*/
virtual void beginGroupPut(PVRecordPtr const & pvRecord) = 0;
/**
* End a set of puts.
* @brief End a set of puts.
* @param pvRecord The record.
*/
virtual void endGroupPut(PVRecordPtr const & pvRecord) = 0;
/**
* Connection to record is being terminated.
* @brief Connection to record is being terminated.
* @param pvRecord The record.
*/
virtual void unlisten(PVRecordPtr const & pvRecord) = 0;
@@ -463,16 +496,17 @@ class epicsShareClass PVDatabase {
public:
POINTER_DEFINITIONS(PVDatabase);
/**
* Get the master database.
* @brief Get the master database.
* @return The shared pointer.
*/
static PVDatabasePtr getMaster();
/**
* Destructor
* @brief Destructor
*/
virtual ~PVDatabase();
/**
* Destroy the PVDatabase.
* @brief Destroy the PVDatabase.
*
* For each record in the database the record is removed and it's destroy method is called.
*/
virtual void destroy();
@@ -484,19 +518,20 @@ public:
*/
PVRecordPtr findRecord(std::string const& recordName);
/**
* Add a record.
* @brief Add a record.
*
* @param record The record to add.
* @return <b>true</b> if record was added.
*/
bool addRecord(PVRecordPtr const & record);
/**
* Remove a record.
* @brief Remove a record.
* @param record The record to remove.
* @return <b>true</b> if record was removed.
*/
bool removeRecord(PVRecordPtr const & record);
/**
* Get the names of all the records in the database.
* @brief Get the names of all the records in the database.
* @return The names.
*/
epics::pvData::PVStringArrayPtr getRecordNames();

View File

@@ -41,21 +41,13 @@ public:
*/
static RemoveRecordPtr create(
std::string const & recordName);
/**
* destructor
*/
virtual ~RemoveRecord();
/**
* Clean up any resources used.
*/
virtual void destroy();
/**
* standard init method required by PVRecord
* @return true unless record name already exists.
*/
virtual bool init();
/**
* Set the trace level.
* @brief Remove the record specified by recordName.
*/
virtual void process();
private:

View File

@@ -35,27 +35,20 @@ class epicsShareClass TraceRecord :
public:
POINTER_DEFINITIONS(TraceRecord);
/**
* Factory methods to create TraceRecord.
* @brief Factory method to create TraceRecord.
*
* @param recordName The name for the TraceRecord.
* @return A shared pointer to TraceRecord..
*/
static TraceRecordPtr create(
std::string const & recordName);
/**
* destructor
*/
virtual ~TraceRecord();
/**
* Clean up any resources used.
*/
virtual void destroy();
/**
* standard init method required by PVRecord
* @return true unless record name already exists.
*/
virtual bool init();
/**
* Set the trace level.
* @brief Set the trace level for record specified by recordName.
*/
virtual void process();
private:

View File

@@ -47,15 +47,6 @@ RemoveRecord::RemoveRecord(
{
}
RemoveRecord::~RemoveRecord()
{
}
void RemoveRecord::destroy()
{
PVRecord::destroy();
}
bool RemoveRecord::init()
{
initPVRecord();

View File

@@ -48,14 +48,6 @@ TraceRecord::TraceRecord(
{
}
TraceRecord::~TraceRecord()
{
}
void TraceRecord::destroy()
{
PVRecord::destroy();
}
bool TraceRecord::init()
{