An Introduction to C++ Programming - Part 11/13

From EDM2
Jump to: navigation, search
An Introduction to C++ Programming / Part
1 2 3 4 5 6 7 8 9 10 11 12 13

Written by Björn Fahller

Auto Pointer

[Note: the source code for this month is auto_ptr.h here. Ed.]

In the past two articles, we've seen how a simple smart pointer, called simply ``ptr<T>'' was used to make memory handling a little bit easier. That is the core purpose of all smart pointers. You can find a few things in common with them all. They're templates, they relieve you of the burden of remembering to deallocate the memory, their syntax resembles that of pointers, they aren't pointers, and they're dangerous if you forget that you're dealing with smart pointers.

While ``ptr<T>'' served its purpose, it's a bit too simplistic to be generally useful. For example there was no way to rebind an object to another pointer, or to tell it not to delete the memory (that too can be useful at times, as we will see later in this article.)

This article is devoted to the only smart pointer provided by the standard C++ library; the class template ``auto_ptr<T>''.

The problem to solve

I do not know what the core issues where when the ``auto_ptr<T>'' was designed, but I know what problems the implementation provided does solve.

  • exception safety
  • safe memory area ownership transfer
  • no confusion with normal pointers
  • controlled and visible rebinding and release of ownership
  • works with dynamic types
  • pointer-like syntax for pointer-like behaviour

Let us have a look at each of these in some detail and compare with the previous ``ptr<T>''.

Exception safety

In this respect ``auto_ptr<T>'' and ``ptr<T>'' are equal. They both delete whatever they point to in their destructor. The only thing that ``auto_ptr<T>'' has to offer over ``ptr<T>'', with respect to exception safety, is that we can tell an ``auto_ptr<T>'' object that it no longer owns a memory area. This can be used for holding onto something we want to return in normal cases, but deallocate in exceptional situations. Here is a code fragment showing such a situation:


  void f(); // may throw something
  int* ptr()
  {
    // returns a newly allocated value on success,
    // or the 0 pointer on failure.
try { auto_ptr<int> p(new int(1)); f(); return p.release(); } catch (...) { return 0; } }

In the code above, an exception thrown from ``f'' results in the destruction of the ``auto_ptr<int>'' object ``p'' before the call of the ``release'' member function, which means that the object pointed to will be deleted.

If, however, ``f'' does not throw any exception, ``p.release()'' is called, and the value returned from there is passed to the caller. The member function ``release'' releases ownership of the memory area from the ``auto_ptr<int>'' object. The value returned is the pointer to the memory area. Since the object no longer owns the memory area, it will not be deallocated.

Safe memory area ownership transfer

This safety is achieved by cheating in the ``assignment'' operator and ``copy'' constructor. The reason I've quoted the names assignment and copy, is that the cheat is so bad that it's not really an assignment and definitely not a copy. Rather, both are ownership transfer operations. What happens is that they both modify the right hand side, by relieving it of ownership while accepting ownership itself. Below are some examples of this:


  // simple transfer
  auto_ptr<int> p1(new int(1));
  // p1 owns the memory area.
  auto_ptr<int> p2;
  // p2 doesn't own anything.
  p2 = p1;
  // now p2 owns the memory area, p1 doesn't.
  // p1 has become the 0 "pointer"
  auto_ptr<int> p3(p2);
  // Now it is p3 that owns the memory area, not
  // p1 or p2.

I think the above example speaks for itself. An important issue here for those of you who have used early versions of the ``auto_ptr<T>'' is that older versions did not become 0 ``pointers'' when not owning the memory area, but that is the behaviour set in the final draft of the C++ standard. Of course, the above program snippet is too simplistic to be useful. The properties of the ``auto_ptr<T>'' are more useful when working with functions, where it works as both documentation and implementation of ownership transfer. What do you think about this?


  auto_ptr<int> creation();
  void termination(auto_ptr<int> rip);
  void f()
  {
    auto_ptr<int> pi=creation();
    // It's now clear that we are responsible for
    // deletion of the memory area allocated. Even
    // if we chose to release ownership from "pi",
    // we must take care of deallocation somehow.

    ... // use pi for something

    termination(pi);

    // since we're sending it off as an auto_ptr<T>,
    // deletion is not our headache anymore, and since
    // the function "termination" wants an auto_ptr<T>
    // it wants the responsibility.
  }

One of the headaches of using dynamically allocated memory is knowing who is responsible for deallocating the memory at any given moment in a program's lifetime. The ``auto_ptr<T>'' makes that rather easy, as can be seen above. Any function that returns an ``auto_ptr<T>'' leaves it to the caller to take care of the deallocation, and any function that accepts an ``auto_ptr<T>'' requires ownership to work. If something goes wrong between calling ``creation'' and ``termination'', such that ``termination'' ought not be called, we must take care of the deallocation, but since we have it in an ``auto_ptr<T>'' that is automatically done for us if we return or throw an exception.

This functionality is an advantage that ``auto_ptr<T>'' offer over ``ptr<T>'', since the latter doesn't have any way of transferring ownership.

No confusion with normal pointers

Since the auto pointers have the behaviour outlined above, it is extremely important that they cannot accidentally be confused with normal pointers. This is done by explicitly prohibiting all implicit conversions between pointer types and ``auto_ptr<T>'' types. The erroneous code below shows how:


  auto_ptr<int> creator();
  void termination(auto_ptr<int>);
  void f()
  {
    int* p = creator();
    // illegal. An auto_ptr<T> cannot be implicitly
    // converted to a pointer.

    auto_ptr<T> ap=p;
    // illegal. A pointer cannot be implicitly
    // converted to an auto_ptr<T>. When creating a
    // new auto_ptr<T> object, use the constructor
    // syntax auto_ptr<T> ap(p);

    ap=p;
    // also illegal. If you want to rebind an
    // auto_ptr<T> object to point to something else,
    // use the "reset" member function; ap.reset(p).

    termination(p);
    // also illegal. The auto_ptr<T> required by the
    // termination function cannot be implicitly
    // created from the pointer.
  }

It is indeed fortunate that the first and last error above are illegal. Imagine the maintenance headaches you could get otherwise. What would the first mean? Would the implicit conversion from ``auto_ptr<T>'' to a raw pointer transfer ownership or not? All implementations I have seen where such implicit conversions are allowed do not transfer the ownership, which in the situation above means that the memory would be deallocated when the ``auto_ptr<T>'' object returned is destroyed (which it would be immediately after the conversion.) The last is as bad. What about this situation?


  int i;
  termination(&i);

Ouch! The function would attempt to delete the local variable. For both the result will be something that in standardese is called ``undefined behaviour'', but which in normal English best translates to ``a crash now, a crash later, or generally funny behaviour (possibly followed by a crash later.)'' Well, since it is illegal, we do not have to worry about it.

The second error ``auto_ptr<int> ap=p;'' is perhaps a bit unfortunate since the intended behaviour is clear. That it is illegal comes as a natural consequence of banning the third situation ``ap=p'' which is not clear. ``ap'' might be declared somewhere far far away, so that in the code near the assignment it is not obvious if it is an ``auto_ptr<T>'' or a normal pointer.

In this respect ``auto_ptr<T>'' is better than ``ptr<T>'', since ``ptr<T>'' does allow implicit construction, allowing the last error.

Controlled and visible rebinding and release of ownership

If we want to rebind an ``auto_ptr<T>'' object to another memory area, it is important that the memory area currently owned by the object (if any) is deallocated. The member function ``reset'' takes care of that. Calling ``ap.reset(p)'' will deallocate whatever ``ap'' owns (if anything) and make it own whatever ``p'' points to.

If we want a normal pointer from an ``auto_ptr<T>'' object, we can get it in two ways, depending on the desired effect. The member function ``release'' gives us a normal pointer to the memory area owned by the ``auto_ptr<T>'' object, and also gives us the ownership, so that we will be responsible for the deallocation. If we do not want that responsibility, but temporarily need a normal pointer to the memory area, we use the ``get'' member function. Here is an example showing the differences:


  void func(const int*); // may throw
  int* f(void)
  {
    auto_ptr<int> p(new int(1));
    func(p.get()); // call func with a normal pointer
    return p.release(); // return the pointer
  }

Above we see that the function ``func'' requires a normal pointer, but it does not assume ownership, so we use the ``get'' member to temporarily get the pointer and pass it to ``func''. This function ``f'' then returns the raw pointer if ``func'' does its job, but if it fails with an exception, the ``auto_ptr<int>'' object ``p'' will deallocate the memory in its destructor.

Since ``ptr<T>'' was specifically designed to disallow transfer of ownership, this functionality is added-value for ``auto_ptr<T>''.

Works with dynamic types

Just as a normal pointer to a base class can point to an object of a publicly derived class, an ``auto_ptr<T>'' can too. This is not particularly strange:


  class A {};
  class B : public A{};
  auto_ptr<A> pa(new B());
  auto_ptr pb(new B());
  pa=pb;
  auto_ptr<A> pa2(pb);
</small>

The reverse is (of course) not allowed. For ``ptr<T>'' this is not a problem, since the functionality is only required if ownership transfer is allowed.

Pointer-like syntax for pointer-like behaviour

For the small subset of a pointer's functionality that is implemented in the ``auto_ptr<T>'' class template, the syntax is exactly the same. We get access to the element pointed to with ``operator*'' and ``operator->''. This is the only functionality of a pointer that is implemented. Here it is a tie between ``auto_ptr<T>'' and ``ptr<T>'', since the functionality is exactly the same and so is the syntax.

Implementation

The definition of ``auto_ptr<T>'' looks as follows:


  template <class T>
  class auto_ptr
  {
  public:
    explicit auto_ptr(T* t = 0) throw ();
    auto_ptr(auto_ptr<T>& t) throw();
    template <class Y> auto_ptr(auto_ptr<Y>& t) throw();
   ~auto_ptr() throw ();
    auto_ptr<T>& operator=(auto_ptr<T>& t) throw ();
    template <class Y>
      auto_ptr<T>& operator=(auto_ptr<Y>& t) throw ();
    T& operator*() const throw ();
    T* operator->() const throw ();
    T* release() throw ();
    void reset(T* t = 0) throw ();
    T* get(void) const throw ();
  private:
    T* p;
  };

Three new details can be seen above. The keyword ``explicit'' in front of the constructor, and ``template <class Y>'' inside the class definition. Both of these are relatively recent additions to the C++ language and far from all compilers support them. Third, and most important (please take note of this,) is that the ``copy'' constructor and ``assignment'' operator do take a non-const reference to their right hand side, so that it can be modified. ``explicit'' is what disallows implicit construction of objects, for example in function calls (see the error example above, when attempting to call a function requiring an ``auto_ptr<T>'' parameter with a normal pointer.) This keyword is, strictly speaking, not needed. There is a fake around it, which you will see when we get to the implementation details. The member templates, as the ``template <class Y>'' used inside the class definition is called, is a way of creating new member functions at need. This is what makes it possible to say ``auto_ptr<A> pa; auto_ptr<B> pb; pa=pb''. With this mini-example, and the code above, we can see that a member function


  auto_ptr<A>&
  auto_ptr<A>::operator=(auto_ptr<B>&) throw()

will be generated. If class ``B'' is publicly derived from class ``A'', the generated code will compile just fine, otherwise we will get an error message from the compiler. This feature can, to the best of my knowledge, not be worked around. It is an essential addition to the C++ language. Unfortunately even fewer compilers support this than support the ``explicit'' keyword.

The code

Let us do the member functions one by one, beginning with the constructor. The only thing it needs to do is to initialize the ``auto_ptr<T>'' object such that it owns the memory area, and if it points to anything at all, it owns it (by definition.)


  template <class T>
  inline auto_ptr<T>::auto_ptr(T* ptr) throw()
   : p(ptr)
  {
  }

The ``inline'' keyword is new for this course, although it has been part of C++ for a very long time. Marking a function ``inline'' is a way of hinting to the compiler that you think this function is so simple that it can insert the function code directly where needed, instead of making a function call. This is just a hint; a compiler is free to ignore it, and likewise a good compiler may inline even functions not marked as inline (provided you cannot see any difference in the behaviour of the program.) Few compilers are smart enough to inline automatically, however, so there's a place for the ``inline'' keyword, and it will be used for all member functions of the ``auto_ptr<T>''.

This constructor is marked ``explicit'' in the class definition. I mentioned above that the ``explicit'' keyword is not, strictly speaking, necessary. Here is the promised work-around:


  template <class T>
  class explicit
  {
  public:
    explicit(T t) : value(t) {};
    operator T() const { return value; };
  private:
    T value;
  };

  template <class T>
  inline auto_ptr<T>::auto_ptr(explicit<T*> ptr) throw()
   : p(ptr)
  {
  }

The way this works is as follows: By default, implicit conversions are allowed, but only one user defined implicit conversion may take place. It is an error if two or more implicit conversions are required to get the desired effect. Constructing an object is a user defined conversion, and executing a conversion operator is too. Look at this example usage:


  void termination(auto_ptr<int> pi);
  void func()
  {
    auto_ptr<int> pi(new int(1)); //**1 legal
    termination(new int(2)); //** 2 error
  }

The code at //**1 is not in error, because we say that we want an object of type ``auto_ptr<int*>''. Since we've been so stern about this, we will be obeyed. It may seem like there are two implicit conversions taking place here, one for creating the ``explicit<T>'' object, and one for getting the value out of it, but that is not quite true. Our ``auto_ptr<int>'' accepts as its parameter an ``explicit<int*>'' which is implicitly created from the pointer value. Then, it is a detail of the innards of the ``auto_ptr<T>'' constructor how it is used, in this case to get the value from it.

The code at //**2 however, is in error, because the call to ``termination'' requires two user defined conversions. One from ``int*'' to ``explicit<int*>'', and one from ``explicit<int*>'' to ``auto_ptr<int>''.

Please see the provided source code for how to allow both versions to coexist for different compilers in the same source file.


  template <class T>
  inline auto_ptr<T>::auto_ptr(auto_ptr<T>& t) throw()
   : p(t.release())
  {
  }

There is not much strange going on here, except that the parameter is a non-const reference. As mentioned far above, the member ``release'' relieves the object of ownership and returns the pointer. Thus this constructor makes ``p'' point to what ``t'' did point to, and alters ``t'' so that it becomes the 0 ``pointer''.


  template <class T> template <class Y>
  inline auto_ptr<T>::auto_ptr(auto_ptr<Y>& t) throw()
   : p(t.release())
  {
  }

The code for this constructor is, of course, the same as for the previous one. Note that both are necessary. I made a mistake with the ``auto_ptr<T>'' implementation available in the adapted SGI STL, that I thought the latter would imply the former. It doesn't, however, even though it may seem so.

Note, by the way, the syntax for a member template, with the two subsequent ``template <...>''

Of course, users of compilers that do not implement member templates will get compilation errors on this member function. Please see the source code for how to work around the compilation error (the work around is simply not to have this member function, which means that the resulting ``auto_ptr'' will be limited in functionality.)


  template <class T>
  inline auto_ptr<T>::~auto_ptr() throw ()
  {
    delete p;
  }

If the object owns anything, it will be deleted by the destructor. Note that deleting the 0 pointer is legal, and does nothing at all. If the object does not own anything, ``p'' will be the 0 pointer.


  template <class T>
  inline auto_ptr<T>&
  auto_ptr<T>::operator=(auto_ptr<T>& t) throw ()
  {
    reset(t.release());
    return *this;
  }

  template <class T> template <class Y>
  inline auto_ptr<T>&
  auto_ptr<T>::operator=(auto_ptr<Y>& t) throw ()
  {
    reset(t.release());
    return *this;
  }

This is pretty much the same story as the ``copy'' constructor. Since we are not creating a new object, however, we cannot just assign to ``p'' (it may point to something, in which case it must be deallocated.) The member function ``reset'' does exactly what we want; delete whatever ``p'' points to, and give it a new value.


  template <class T>
  inline T& auto_ptr<T>::operator*() const throw ()
  {
    return *p;
  }

  template <class T>
  inline T* auto_ptr<T>::operator->() const throw ()
  {
    return p;
  }

These are not identical with the version of ``ptr<T>'' from the previous issue of the course. One word on the way, though. ``operator->'' can, of course, only be used if ``T'' is a struct or class type. On some older compilers, it's even illegal to instantiate ``auto_ptr<T>'' if ``T'' is not a struct or class type. In most cases this is a minor limitation; after all, it is normally structs and classes you handle this way, and not built-in types.


  template <class T>
  inline T* auto_ptr<T>::release() throw ()
  {
    T* tp=p;
    p=0;
    return tp;
  }

Not much to say, is there? The object is relieved of ownership by making ``p'' the 0 pointer, and the value previously held by ``p'' is returned; just as mentioned in the introduction of the class.


  template <class T>
  inline void auto_ptr<T>::reset(T* t) throw ()
  {
    if (t != p) {
      delete p;
      p=t;
    }
  }

Deletes what it points to and sets ``p'' to the given value. Nothing strange, except the safety guard against resetting to the value already held. If we didn't have this guard, resetting to the current value would deallocate the memory and keep the ownership of it, for later deletion again! It seems like a better way is to just do nothing if the situation ever arises.


  template <class T>
  inline T* auto_ptr<T>::get(void) const throw ()
  {
    return p;
  }

Not much to say about this one.

Efficiency

The question of efficiency pops up now and then. How much does it cost, performance and memory-wise to use the ``auto_ptr<T>'' instead of ``ptr<T>'' from last month?

If you use ``auto_ptr<T>'' instead of ``ptr<T>'', and use only the functionality that ``ptr<T>'' offers, the price is nothing at all. The constructor, destructor, ``operator*'' and ``operator->'' holds exactly the same code for both templates. You pay for what you use only.

Compared to raw pointers and doing your own deletion? I do not know. It will depend a lot on how clever your compiler is with inlining. Most probably close to none at all. If you have a measurable speed difference in a real-world application, I would say the difference is that with ``auto_ptr<T>'' you do many more deletions (i.e. you have mended memory leaks you were not aware of having.)

Recap

The news this month were:

  • The standard class template ``auto_ptr<T>'' handles memory deallocation and ownership transfer.
  • Automatic memory deallocation and ownership transfer reduces the risk for memory leaks, especially when exceptions occur.
  • Implicit conversions between raw pointers and smart pointers is bad (even if it may seem tempting at first.)
  • The ``explicit'' keyword disallows implicit construction of objects.
  • The ``explicit'' keyword can be faked.
  • Member templates can be used to create member functions at compile time, just like function templates can be used to create functions at compile time.
  • ``inline'' hints to a compiler that you think a function is so small that it is better to directly insert the function code where required instead of making a function call.

Exercises

  • Why is it a bad idea to have arrays (or other collections) of ``auto_ptr<T>''?
  • Can smart pointers be dangerous? When? ``auto_ptr<T>'' too?
  • What is a better name for this function template?

  template <class T>
  void funcname(auto_ptr<T>)
  {
  }

  • What happens if ~T throws an exception?

Coming up

If I missed something, or you want something clarified further or disagree with me, please drop me a line and I'll address your ideas in future articles.

Next month we'll have a look at a smarter pointer; a reference counted one. I'm beginning to dry up on topics now, however, so please write and give me suggestions for future topics to cover.