c++ - What is "rvalue reference for *this"?

itemprop="text">

Came across a proposal
called "rvalue reference for *this" in clang's href="http://clang.llvm.org/cxx_status.html">C++11 status
page.

I've read quite a bit about
rvalue references and understood them, but I don't think I know about this. I also
couldn't find much resources on the web using the
terms.

There's a link to the proposal paper on
the page: href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm">N2439
(Extending move semantics to *this), but I'm also not getting much examples from
there.

What is this feature about?

style="font-weight: bold;">

Answer

First, "ref-qualifiers for *this" is a just a
"marketing statement". The type of *this never changes, see the
bottom of this post. It's way easier to understand it with this wording
though.

Next, the following code
chooses the function to be called based on the ref-qualifier of the
"implicit object parameter" of the
function^†:

//
            t.cpp
#include 

struct test{

            void f() &{ std::cout << "lvalue object\n"; }
 void f() &&{
            std::cout << "rvalue object\n"; }
};


int
            main(){
 test t;
 t.f(); // lvalue
 test().f(); //
            rvalue
}

Output:

$
            clang++ -std=c++0x -stdlib=libc++ -Wall -pedantic t.cpp
$
            ./a.out
lvalue object
rvalue
            object

The whole thing
is done to allow you to take advantage of the fact when the object the function is
called on is an rvalue (unnamed temporary, for example). Take the following code as a
further example:

struct
            test2{
 std::unique_ptr
            heavy_resource;


 test2()
 : heavy_resource(new
            int[500]) {}

 operator std::unique_ptr()
            const&{
 // lvalue object, deep copy

            std::unique_ptr p(new int[500]);
 for(int i=0; i < 500;
            ++i)
 p[i] = heavy_resource[i];


 return
            p;
 }

 operator std::unique_ptr()
            &&{
 // rvalue object
 // we are garbage anyways, just move
            resource
 return std::move(heavy_resource);

            }
};

This
may be a bit contrived, but you should get the
idea.

Note that you can combine the
cv-qualifiers (const and
volatile) and ref-qualifiers
(& and
&&).

/>

^{Note: Many standard quotes and overload
resolution explanation after here!}

†
To understand how this works, and why @Nicol Bolas' answer is at least partly wrong, we
have to dig in the C++ standard for a bit (the part explaining why @Nicol's answer is
wrong is at the bottom, if you're only interested in
that).

Which function is going to be
called is determined by a process called overload resolution. This
process is fairly complicated, so we'll only touch the bit that is important to
us.

First, it's important to see how overload
resolution for member functions
works:

§13.3.1
[over.match.funcs]

p2 The set of candidate functions can contain both member and non-member
functions to be resolved against the same argument list. So that argument and parameter
lists are comparable within this heterogeneous set, a member function is
considered to have an extra parameter, called the implicit object parameter, which
represents the object for which the member function has been called.
[...]

p3 Similarly, when
appropriate, the context can construct an argument list that contains an
implied object argument to denote the object to be operated
on.

Why do we even
need to compare member and non-member functions? Operator overloading, that's why.
Consider this:

struct
            foo{
 foo& operator<<(void*); // implementation
            unimportant
};

foo& operator<<(foo&, char
            const*); // implementation
            unimportant

You'd
certainly want the following to call the free function, don't
you?

char const* s = "free
            foo!\n";
foo f;
f <<
            s;

That's why member
and non-member functions are included in the so-called overload-set. To make the
resolution less complicated, the bold part of the standard quote exists. Additionally,
this is the important bit for us (same
clause):

p4 For non-static member functions, the type of the implicit object parameter
is

• “lvalue
  reference to cv X” for functions declared
  without a ref-qualifier or with the &
  ref-qualifier





• “rvalue reference to cv
  X” for functions declared with the
  &&
  ref-qualifier

where X is the
class of which the function is a member and cv is the
cv-qualification on the member function declaration.
[...]

p5 During overload resolution
[...] [t]he implicit object parameter [...] retains its identity since conversions on
the corresponding argument shall obey these additional rules:

• no temporary object can be
  introduced to hold the argument for the implicit object parameter;
  and




• no user-defined conversions can
  be applied to achieve a type match with it

[...]

(The
last bit just means that you can't cheat overload resolution based on implicit
conversions of the object a member function (or operator) is called
on.)

Let's take the first example at the top of
this post. After the aforementioned transformation, the overload-set looks something
like this:

void f1(test&); //
            will only match lvalues, linked to 'void test::f() &'
void
            f2(test&&); // will only match rvalues, linked to 'void test::f()
            &&'

Then the
argument list, containing an implied object argument, is matched
against the parameter-list of every function contained in the overload-set. In our case,
the argument list will only contain that object argument. Let's see how that looks
like:

// first call to
            'f' in 'main'
test t;
f1(t); // 't' (lvalue) can match 'test&'
            (lvalue reference)
 // kept in overload-set
f2(t); // 't' not an
            rvalue, can't match 'test&&' (rvalue reference)
 // taken out of
            overload-set

If, after
all overloads in the set are tested, only one remains, the overload resolution succeeded
and the function linked to that transformed overload is called. The same goes for the
second call to 'f':

//
            second call to 'f' in 'main'
f1(test()); // 'test()' not an lvalue, can't
            match 'test&' (lvalue reference)
 // taken out of
            overload-set
f2(test()); // 'test()' (rvalue) can match 'test&&'
            (rvalue reference)
 // kept in
            overload-set

Note
however that, had we not provided any ref-qualifier (and as such
not overloaded the function), that f1
would match an rvalue (still
§13.3.1):

p5 [...] For non-static member functions declared without a
ref-qualifier, an additional rule applies:

• even if the implicit object parameter is not
  const-qualified, an rvalue can be bound to the parameter as
  long as in all other respects the argument can be converted to the type of the implicit
  object parameter.

struct
            test{
 void f() { std::cout << "lvalue or rvalue object\n";
            }

};

int main(){
 test t;

            t.f(); // OK
 test().f(); // OK
            too
}

/>

Now, onto why @Nicol's answer is atleast
partly wrong. He says:

Note that this declaration changes the type of
*this.

That
is wrong, *this is always an
lvalue:

§5.3.1 [expr.unary.op]
p1

The unary * operator performs
indirection: the expression to which it is applied shall be a
pointer to an object type, or a pointer to a function type and the result
is an lvalue referring to the object or function to which the expression
points.

§9.3.2
[class.this]
p1

In
the body of a non-static (9.3) member function, the keyword
this is a prvalue expression whose value is the address of the
object for which the function is called. The type of this in a
member function of a class X is X*.
[...]