Permalink
Browse files

update port to mrpt 2.0 doc

  • Loading branch information...
jlblancoc committed Jan 10, 2018
1 parent dc9ad8c commit 0cc86f97d04113a0bb597888a1f81e039b9553d9
Showing with 116 additions and 90 deletions.
  1. +116 −90 doc/doxygen-pages/porting_mrpt2.h
@@ -5,95 +5,121 @@
| Copyright (c) 2005-2017, Individual contributors, see AUTHORS file |
| See: http://www.mrpt.org/Authors - All rights reserved. |
| Released under BSD License. See details in http://www.mrpt.org/License |
+---------------------------------------------------------------------------+ */
+---------------------------------------------------------------------------+
*/
/** \page porting_mrpt2 Porting code from MRPT 1.{3,4,5} to MRPT 2.*
*
* MRPT 2.0 includes several fundamental changes, most of them related to API clean ups
* and the introduction of C++14 as the minimum supported version of the language.
*
* Existing user applications may need to be adapted to continue compiling and working
* as usual after updating to MRPT 2.*:
*
* **Mandatory changes**
* - Your project must use C++14. Using CMake this is easy by adding this right after your top-level `PROJECT`:
* \code
* CMAKE_MINIMUM_REQUIRED(VERSION 3.1)
* set (CMAKE_CXX_STANDARD 14) # Require C++14
* \endcode
* - **Smart pointers** are now standard [`std::shared_ptr<>`](http://en.cppreference.com/w/cpp/memory/shared_ptr) instead of those based on `stlplus`. Required changes:
* - `ptr.clear()` --> `ptr.reset()`. Also, notice that the former `stlplus` semantics of `clear()` deleting **all** copies of the object, as hold by different smart pointers, is no longer maintained. There is no longer such a possibility, since the C++11 standard does not allow it to happen (and it makes sense in this way).
* - `ptr.clear_unique()` --> `ptr.reset()`. (Read this note above)
* - `ptr.make_unique()` does no longer exists, and does not make sense (read above).
* - `ptr.pointer()` --> `ptr.get()`
* - Smart pointers have been renamed from `CFooPtr` to the more standard `CFoo::Ptr`, with a new pointer-to-const version `CFoo::ConstPtr`.
* - Note: To help with porting and maintaining existing code bases, MRPT >=1.5.4 offers MRPT2-like `CFoo::Ptr` smart pointers. Refer to changelog of mrpt 1.5.4.
* - You can keep using code like:
* \code
* CFoo::Ptr o = CFoo::Create();
* \endcode
* in MRPT 2.0 to create a smart pointer, but can also use `std::make_shared<CFoo>()`, or `mrpt::make_aligned_shared<CFoo>()` if the class must be memory-aligned (typically, if it contains Eigen matrices).
* The arguments of `Create()` are now [perfectly-forwarded](http://en.cppreference.com/w/cpp/utility/forward) to the class ctor, so the parameter list must exactly match any of the available ctors.
* - Smart pointer typecasting now is done via C++11 standard functions:
* - Example: Old code
* \code
* CObservationPtr obs = getObsFromSomewhere();
* CObservationGPSPtr gps = CObservationGPS(obs);
* \endcode
* becomes pure C++14 in MRPT 2.0:
* \code
* CObservation::Ptr obs = getObsFromSomewhere();
* CObservationGPS::Ptr gps = std::dynamic_pointer_cast<CObservationGPS>(obs);
* \endcode
* or, if you need to keep your code compatible with MRPT >=1.5.4:
* \code
* CObservation::Ptr obs = getObsFromSomewhere();
* CObservationGPS::Ptr gps = mrpt::ptr_cast<CObservationGPS>::from(obs);
* \endcode
* - Threads, semaphores and mutexes are now based on C++11 standard library. Required changes:
* - `mrpt::synch::CCriticalSection cs;` --> `std::mutex cs;`
* - `mrpt::synch::CCriticalSectionLocker lock(&cs);` --> `std::lock_guard<std::mutex> lock(cs);`
* - `mrpt::system::TThreadHandle h = mrpt::system::createThread(...);` --> `std::thread h = std::thread(...);`
* - `mrpt::system::sleep(5);` --> `std::this_thread::sleep_for(5ms);`
* - `mrpt::synch::CSemaphore sem; sem.waitForSignal(timeout); sem.release();` --> `std::promise<void> sem; auto fut = sem.get_future(); fut.wait_for(...); sem.set_value();`
* - `mrpt::utils::CObject::duplicate()` has been removed, use the equivalent (redundant) `mrpt::utils::CObject::clone()`.
* - CSerialPort, `mrpt::utils::net`, sockets: have been moved to its own new module \ref mrpt_comms_grp under namespace `mrpt::comms`.
* - Static variables have been dropped in favor of global getter/setter functions. This allowed removing all DLL import/export macros for Windows compilers. Important changes are:
* - `mrpt::math::randomGenerator` --> `mrpt::math::getRandomGenerator()`
* - `mrpt::global_settings` old static variables have been replaced by getter/setter functions.
* - Serialization: See tutorial of the new module \ref mrpt_serialization_grp
* - To serialize an object to/from a CStream, you must now use CArchive:
* \code
* CStreamXXXX f; // Any mrpt::io::CStream type
* auto arch = mrpt::serialization::archiveFrom(f);
* arch << object;
* arch >> object;
* \endcode
* - The two methods `writeToStream()` and `readFromStream()` of old `CSerializable` classes
* must be replaced by the three methods: `serializeGetVersion()`, `serializeTo()`, and `serializeTo()`.
* See tutorials in \ref mrpt_serialization_grp.
* - Implicit constructor to convert from mrpt::poses::CPose3D to mrpt::math::TPose3D has been removed, due to the refactoring of mrpt::math and mrpt::poses into separate libraries.
* To convert CPose3D -> TPose3D, use the new method mrpt::poses::CPose3D::asTPose()
* \code
* mrpt::poses::CPose3D p1;
* mrpt::math::TPose3D p2 = p1; // ERROR in mrpt 2.0 (built in MRPT 1.*)
* mrpt::math::TPose3D p3 = p1.asTPose(); // OK for mrpt 2.0
* \endcode
* - 16-bytes memory-aligned STL containers are now defined in separate headers, one for each container type, and based on templatized `using`. Example:
* \code
* // Old: MRPT 1.* code
* #include <mrpt/core/aligned_std_vector.h>
* mrpt::aligned_std_vector<Foo> v;
*
* // New: MRPT 2.* code
* #include <mrpt/core/aligned_std_vector.h>
* mrpt::aligned_std_vector<Foo> v;
* \endcode
*
*
*
* **Optional changes**
* - Use the `Foo::ConstPtr` smart pointers when possible instead of its non-const counterpart.
*
*
*/
*
* MRPT 2.0 includes several fundamental changes, most of them related to API
* clean ups and the introduction of C++14 as the minimum supported version of
* the language.
*
* Existing user applications may need to be adapted to continue compiling and
* working as usual after updating to MRPT 2.*:
*
* **Mandatory changes**
* - Your project must use C++14. Using CMake this is easy by adding this right
* after your top-level `PROJECT`: \code CMAKE_MINIMUM_REQUIRED(VERSION 3.1) set
* (CMAKE_CXX_STANDARD 14) # Require C++14 \endcode
* - **Smart pointers** are now standard
* [`std::shared_ptr<>`](http://en.cppreference.com/w/cpp/memory/shared_ptr)
* instead of those based on `stlplus`. Required changes:
* - `ptr.clear()` --> `ptr.reset()`. Also, notice that the former
* `stlplus` semantics of `clear()` deleting **all** copies of the object, as
* hold by different smart pointers, is no longer maintained. There is no longer
* such a possibility, since the C++11 standard does not allow it to happen (and
* it makes sense in this way).
* - `ptr.clear_unique()` --> `ptr.reset()`. (Read this note above)
* - `ptr.make_unique()` does no longer exists, and does not make sense
* (read above).
* - `ptr.pointer()` --> `ptr.get()`
* - Smart pointers have been renamed from `CFooPtr` to the more standard
* `CFoo::Ptr`, with a new pointer-to-const version `CFoo::ConstPtr`.
* - Note: To help with porting and maintaining existing code bases, MRPT
* >=1.5.4 offers MRPT2-like `CFoo::Ptr` smart pointers. Refer to changelog of
* mrpt 1.5.4.
* - You can keep using code like:
* \code
* CFoo::Ptr o = CFoo::Create();
* \endcode
* in MRPT 2.0 to create a smart pointer, but can also use
* `std::make_shared<CFoo>()`, or `mrpt::make_aligned_shared<CFoo>()` if the
* class must be memory-aligned (typically, if it contains Eigen matrices). The
* arguments of `Create()` are now
* [perfectly-forwarded](http://en.cppreference.com/w/cpp/utility/forward) to
* the class ctor, so the parameter list must exactly match any of the available
* ctors.
* - Smart pointer typecasting now is done via C++11 standard functions:
* - Example: Old code
* \code
* CObservationPtr obs = getObsFromSomewhere();
* CObservationGPSPtr gps = CObservationGPS(obs);
* \endcode
* becomes pure C++14 in MRPT 2.0:
* \code
* CObservation::Ptr obs = getObsFromSomewhere();
* CObservationGPS::Ptr gps =
* std::dynamic_pointer_cast<CObservationGPS>(obs); \endcode or, if you need to
* keep your code compatible with MRPT >=1.5.4: \code CObservation::Ptr obs =
* getObsFromSomewhere(); CObservationGPS::Ptr gps =
* mrpt::ptr_cast<CObservationGPS>::from(obs); \endcode
* - Threads, semaphores and mutexes are now based on C++11 standard library.
* Required changes:
* - `mrpt::synch::CCriticalSection cs;` --> `std::mutex cs;`
* - `mrpt::synch::CCriticalSectionLocker lock(&cs);` -->
* `std::lock_guard<std::mutex> lock(cs);`
* - `mrpt::system::TThreadHandle h = mrpt::system::createThread(...);` -->
* `std::thread h = std::thread(...);`
* - `mrpt::system::sleep(5);` --> `std::this_thread::sleep_for(5ms);`
* - `mrpt::synch::CSemaphore sem; sem.waitForSignal(timeout);
* sem.release();` --> `std::promise<void> sem; auto fut = sem.get_future();
* fut.wait_for(...); sem.set_value();`
* - `mrpt::utils::CObject::duplicate()` has been removed, use the equivalent
* (redundant) `mrpt::utils::CObject::clone()`.
* - CSerialPort, `mrpt::utils::net`, sockets: have been moved to its own new
* module \ref mrpt_comms_grp under namespace `mrpt::comms`.
* - Static variables have been dropped in favor of global getter/setter
* functions. This allowed removing all DLL import/export macros for Windows
* compilers. Important changes are:
* - `mrpt::math::randomGenerator` --> `mrpt::math::getRandomGenerator()`
* - `mrpt::global_settings` old static variables have been replaced by
* getter/setter functions.
* - `ASSERT_*` macros must now be ended with a semicolon, e.g. `ASSERT_(a>0);`
* - Serialization: See tutorial of the new module \ref mrpt_serialization_grp
* - To serialize an object to/from a CStream, you must now use CArchive:
* \code
* CStreamXXXX f; // Any mrpt::io::CStream type
* auto arch = mrpt::serialization::archiveFrom(f);
* arch << object;
* arch >> object;
* \endcode
* - The two methods `writeToStream()` and `readFromStream()` of old
* `CSerializable` classes must be replaced by the three methods:
* `serializeGetVersion()`, `serializeTo()`, and `serializeTo()`. See tutorials
* in \ref mrpt_serialization_grp.
* - Implicit constructor to convert from mrpt::poses::CPose3D to
* mrpt::math::TPose3D has been removed, due to the refactoring of mrpt::math
* and mrpt::poses into separate libraries. To convert CPose3D -> TPose3D, use
* the new method mrpt::poses::CPose3D::asTPose() \code mrpt::poses::CPose3D p1;
* mrpt::math::TPose3D p2 = p1; // ERROR in mrpt 2.0 (built in
* MRPT 1.*) mrpt::math::TPose3D p3 = p1.asTPose(); // OK for mrpt 2.0 \endcode
* - 16-bytes memory-aligned STL containers are now defined in separate
* headers, one for each container type, and based on templatized `using`.
* Example: \code
* // Old: MRPT 1.* code
* #include <mrpt/core/aligned_std_vector.h>
* mrpt::aligned_std_vector<Foo> v;
*
* // New: MRPT 2.* code
* #include <mrpt/core/aligned_std_vector.h>
* mrpt::aligned_std_vector<Foo> v;
* \endcode
*
*
*
* **Optional changes**
* - Use the `Foo::ConstPtr` smart pointers when possible instead of its
* non-const counterpart.
*
*
*/

0 comments on commit 0cc86f9

Please sign in to comment.