Frequently Asked Questions (FAQ) about Thyra Software

Outline

• Questions about the smart pointer class Teuchos::RefCountPtr
  • Q: What are RefCountPtr objects and why are they important?
  • Q: Do I really have to write &*ptr all the time?
  • Q: Should my code use RefCountPtr's everywhere?

• Questions about Fundamental Thyra Operator/Vector Interfaces
  • Q: Why is Thyra written with so many non-member helper functions instead of member functions?
  • Q: Where is the Scalar class, and how do I use it to replace my underlying data-type, e.g. double, in my ANA?
  • Q: How do I create a Thyra::VectorBase or Thyra::MultiVectorBase object?

Questions about the smart pointer class Teuchos::RefCountPtr

Q: What are RefCountPtr objects and why are they important?

A:The class Teuchos::RefCountPtr implements a form of reference counting which, through the magic of smart pointers in C++, allows objects to be created and used without much concern for when and where they should be deleted. It is a form of garbage collection but is not as general or fail- safe as in languages with built in garbage collection. For more information see:

http://software.sandia.gov/Trilinos/RefCountPtrBeginnersGuideSAND.pdf

and click on: Teuchos::RefCountPtr

Q: Do I really have to write &*ptr all the time?

What are the benefits of &* vs. get()?

A: There are two ways to get at the underlying raw pointer to an object that is wrapped in the RefCountPtr<C> object c_ptr:

C *c_rptr1 = c_ptr.get(); // Unchecked, can be NULL
C *c_rptr2 = &*c_ptr;     // Checked in debug build and will not return NULL

You should use c_ptr.get() when it is okay for the pointer to be NULL. On the other hand, you should use &*c_ptr when you don't want to allow the raw pointer to be NULL. This is because the operator function <tt>Teuchos::RefCountPtr::operator*() will throw an exception if Teuchos::RefCountPtr::get()==NULL when the code is compiled using the macro define -D_DEBUG.

For more information see Item 3 in Appendix B in

http://software.sandia.gov/Trilinos/RefCountPtrBeginnersGuideSAND.pdf

Q: Should my code use RefCountPtr's everywhere?

A: You should only use RefCountPtr to wrap objects where a persisting relationship is being formed or maintained. For non-persisting relationships, use raw C++ references and pointers.

For more information see the main body and Appendix D of the document:

http://software.sandia.gov/Trilinos/RefCountPtrBeginnersGuideSAND.pdf

Questions about Fundamental Thyra Operator/Vector Interfaces

Q: Why is Thyra written with so many non-member helper functions instead of member functions?

In standard C++ class students were told that the beauty of OOP is that functions and data can be put together into classes to combine the operations with the data on which they operate.

A: Generally member functions should only be used over non-member functions when direct access to private or protected data for functions is required. By minimizing the amount of code that can access non-public data you greatly simplify maintenance. See section 11.3.1 in "The C++ Programming Language: Special Edition" for a discussion of this topic.

Q: Where is the Scalar class, and how do I use it to replace my underlying data-type, e.g. double, in my ANA?

A: The 'Scalar' class is in a template argument in all of the core Thyra interface code. The goal of this template argument is to allow many abstract numerical algorithms to be written in a general form to support a number of different scalar types (e.g. real, complex, extended precision etc.). While the interfaces, the composite classes, and many of the concrete implementations are fully templated some are not and can only support one scalar type (e.g. see the Epetra/Thyra adapters).

See the Thyra::sillyCgSolve() and Thyra::sillyPowerMethod() examples for how this templating is used.

Q: How do I create a Thyra::VectorBase or Thyra::MultiVectorBase object?

The member functions Thyra::VectorSpaceBase::createMember() and Thyra::VectorSpaceBase::createMembers() are protected and can not be called by client code.

A: You must use the non-member functions Thyra::createMember() and Thyra::createMembers() described here.

---