aepko/Ardupilot2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add more documentation for AP_MetaClass.

Browse Source 
git-svn-id: https://arducopter.googlecode.com/svn/trunk@1465 f9c3cf11-9bcb-44bc-f272-b75c42450872
This commit is contained in:
DrZiplok@gmail.com 2011-01-10 01:43:41 +00:00
parent 44cac7a853
commit 6366cdc094
2 changed files with 77 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
libraries/AP_Common/AP_MetaClass.h
View File

@ -7,9 +7,15 @@
//
/// @file AP_MetaClass.h
/// Abstract meta-class from which other AP classes may inherit.
/// Provides type introspection and some basic protocols that can
/// be implemented by subclasses.
/// @brief An abstract base class from which other classes can inherit.
///
/// This abstract base class declares and implements functions that are
/// useful to code that wants to know things about a class, or to operate
/// on the class without knowing precisely what it is.
///
/// All classes that inherit from this class can be assumed to have these
/// basic functions.
///
#ifndef AP_METACLASS_H
#define AP_METACLASS_H
@ -29,21 +35,39 @@ public:
/// Default constructor does nothing.
AP_MetaClass(void);
/// Default destructor is virtual, to ensure that all destructors
/// are called for derived classes.
/// Default destructor is virtual, to ensure that all subclasses'
/// destructors are virtual. This guarantees that all destructors
/// in the inheritance chain are called at destruction time.
///
virtual ~AP_MetaClass();
/// Type code, unique to all instances of a given subclass.
/// Typedef for the ID unique to all instances of a class.
///
/// See ::meta_type_id for a discussion of class type IDs.
///
typedef uint16_t AP_TypeID;
/// Obtain a value unique to all instances of a specific subclass.
///
/// The value can be used to determine whether two class pointers
/// refer to the same exact class type. The value can also be cached
/// and then used to detect objects of a given type at a later point.
///
/// This is similar to the basic functionality of the C++ typeid
/// keyword, but does not depend on std::type_info or any compiler-
/// generated RTTI.
///
/// As the value is derived from the vtable address, it cannot be
/// introspected outside the current state of the system.
/// The value is derived from the vtable address, so it is guaranteed
/// to be unique but cannot be known until the program has been compiled
/// and linked. Thus, the only way to know the type ID of a given
/// type is to construct an object at runtime. To cache the type ID
/// of a class Foo, one would write:
///
/// AP_MetaClass::AP_TypeID Foo_type_id;
///
/// { Foo a; Foo_type_id = a.meta_type_id(); }
///
/// This will construct a temporary Foo object a and save its type ID.
///
/// @param p A pointer to an instance of a subclass of AP_MetaClass.
/// @return A type-unique value.
@ -56,6 +80,10 @@ public:
/// enough information to construct and validate a pointer to the instance
/// when passed back from an untrusted source.
///
/// Handles are useful when passing a reference to an object to a client outside
/// the system, as they can be validated by the system when the client hands
/// them back.
///
typedef uint32_t AP_MetaHandle;
/// Return a value that can be used as an external pointer to an instance
@ -111,9 +139,17 @@ public:
/// Tests whether two objects are of precisely the same class.
///
/// Note that for p2 inheriting from p1, this will return false.
/// Even with RTTI not disabled, there does not seem to be enough information
/// to determine whether one class inherits from another.
/// Note that in the case where p2 inherits from p1, or vice-versa, this will return
/// false as we cannot detect these inheritance relationships at runtime.
///
/// In the caller's context, p1 and p2 may be pointers to any type, but we require
/// that they be passed as pointers to AP_MetaClass in order to make it clear that
/// they should be pointers to classes derived from AP_MetaClass.
///
/// No attempt is made to validate whether p1 and p2 are actually derived from
/// AP_MetaClass. If p1 and p2 are equal, or if they point to non-class objects with
/// similar contents, or to non-AP_MetaClass derived classes with no virtual functions
/// this function may return true.
///
/// @param p1 The first object to be compared.
/// @param p2 The second object to be compared.
@ -124,7 +160,11 @@ public:
return p1->meta_type_id() == p2->meta_type_id();
}
/// Cast an object to an expected class type.
/// Cast a pointer to an expected class type.
///
/// This function is used when a pointer is expected to be a pointer to a
/// subclass of AP_MetaClass, but the caller is not certain. It will return the pointer
/// if it is, or NULL if it is not a pointer to the expected class.
///
/// This should be used with caution, as _typename's default constructor and
/// destructor will be run, possibly introducing undesired side-effects.
@ -146,36 +186,42 @@ public:
return NULL;
}
/// Serialise the class.
/// Serialize the class.
///
/// Serialisation provides a mechanism for exporting the state of the class to an
/// Serialization stores the state of the class in an external buffer in such a
/// fashion that it can later be restored by unserialization.
///
/// AP_MetaClass subclasses should only implement these functions if saving and
/// restoring their state makes sense.
///
/// Serialization provides a mechanism for exporting the state of the class to an
/// external consumer, either for external introspection or for subsequent restoration.
///
/// Classes that wrap variables should define the format of their serialised data
/// Classes that wrap variables should define the format of their serialiaed data
/// so that external consumers can reliably interpret it.
///
/// @param buf Buffer into which serialised data should be placed.
/// @param bufSize The size of the buffer provided.
/// @return The size of the serialised data, even if that data would
/// have overflowed the buffer. If the return value is zero,
/// the class does not support serialisation.
/// the class does not support serialization.
///
virtual size_t serialize(void *buf, size_t bufSize) const;
/// Unserialise the class.
/// Unserialize the class.
///
/// Unserialising a class from a buffer into which the class previously serialised
/// itself restores the instance to an identical state, where "identical" may be
/// defined in context.
/// Unserializing a class from a buffer into which the class previously serialized
/// itself restores the instance to an identical state, where "identical" is left
/// up to the class itself to define.
///
/// Classes that wrap variables should define the format of their serialised data so
/// Classes that wrap variables should define the format of their serialized data so
/// that external providers can reliably encode it.
///
/// @param buf Buffer containing serialised data.
/// @param buf Buffer containing serialized data.
/// @param bufSize The size of the buffer.
/// @return The number of bytes from the buffer that would be consumed
/// unserialising the data. If the value is less than or equal
/// to bufSize, unserialisation was successful. If the return
/// unserializing the data. If the value is less than or equal
/// to bufSize, unserialization was successful. If the return
/// value is zero the class does not support unserialisation or
/// the data in the buffer is invalid.
///

7
libraries/AP_Common/AP_Var.h
View File

@ -5,6 +5,13 @@
// Free Software Foundation; either version 2.1 of the License, or (at
// your option) any later version.
//
/// @file AP_Var.h
/// @brief A system for managing and storing variables that are of
/// general interest to the system.
///
///
/// The AP variable interface. This allows different types
/// of variables to be passed to blocks for floating point
/// math, memory management, etc.