Macro glib::clone

clone!() { /* proc-macro */ }

Macro for passing variables as strong or weak references into a closure.

This macro can be useful in combination with closures, e.g. signal handlers, to reduce the boilerplate required for passing strong or weak references into the closure. It will automatically create the new reference and pass it with the same name into the closure.

If upgrading the weak reference to a strong reference inside the closure is failing, the closure is immediately returning an optional default return value. If none is provided, () is returned.

⚠️ IMPORTANT ⚠️

glib needs to be in scope, so unless it’s one of the direct crate dependencies, you need to import it because clone! is using it. For example:

use gtk::glib;

Debugging

In case something goes wrong inside the clone! macro, we use the g_debug macro. Meaning that if you want to see these debug messages, you’ll have to set the G_MESSAGES_DEBUG environment variable when running your code (either in the code directly or when running the binary) to either “all” or CLONE_MACRO_LOG_DOMAIN:

use glib::CLONE_MACRO_LOG_DOMAIN;

std::env::set_var("G_MESSAGES_DEBUG", CLONE_MACRO_LOG_DOMAIN);
std::env::set_var("G_MESSAGES_DEBUG", "all");

Or:

$ G_MESSAGES_DEBUG=all ./binary

Passing a strong reference

use glib;
use glib_macros::clone;
use std::rc::Rc;

let v = Rc::new(1);
let closure = clone!(@strong v => move |x| {
    println!("v: {}, x: {}", v, x);
});

closure(2);

Passing a weak reference

use glib;
use glib_macros::clone;
use std::rc::Rc;

let u = Rc::new(2);
let closure = clone!(@weak u => move |x| {
    println!("u: {}, x: {}", u, x);
});

closure(3);

Allowing a nullable weak reference

In some cases, even if the weak references can’t be retrieved, you might want to still have your closure called. In this case, you need to use @weak-allow-none:

use glib;
use glib_macros::clone;
use std::rc::Rc;

let closure = {
    // This `Rc` won't be available in the closure because it's dropped at the end of the
    // current block
    let u = Rc::new(2);
    clone!(@weak-allow-none u => @default-return false, move |x| {
        // We need to use a Debug print for `u` because it'll be an `Option`.
        println!("u: {:?}, x: {}", u, x);
        true
    })
};

assert_eq!(closure(3), true);

Creating owned values from references (ToOwned)

use glib;
use glib_macros::clone;

let v = "123";
let closure = clone!(@to-owned v => move |x| {
    // v is passed as `String` here
    println!("v: {}, x: {}", v, x);
});

closure(2);

Renaming variables

use glib;
use glib_macros::clone;
use std::rc::Rc;

let v = Rc::new(1);
let u = Rc::new(2);
let closure = clone!(@strong v as y, @weak u => move |x| {
    println!("v as y: {}, u: {}, x: {}", y, u, x);
});

closure(3);

Providing a default return value if upgrading a weak reference fails

You can do it in two different ways:

Either by providing the value yourself using @default-return:

use glib;
use glib_macros::clone;
use std::rc::Rc;

let v = Rc::new(1);
let closure = clone!(@weak v => @default-return false, move |x| {
    println!("v: {}, x: {}", v, x);
    true
});

// Drop value so that the weak reference can't be upgraded.
drop(v);

assert_eq!(closure(2), false);

Or by using @default-panic (if the value fails to get upgraded, it’ll panic):

let closure = clone!(@weak v => @default-panic, move |x| {
    println!("v: {}, x: {}", v, x);
    true
});

Errors

Here is a list of errors you might encounter:

Missing @weak or @strong:

let v = Rc::new(1);

let closure = clone!(v => move |x| println!("v: {}, x: {}", v, x));

Passing self as an argument:

#[derive(Debug)]
struct Foo;

impl Foo {
    fn foo(&self) {
        let closure = clone!(@strong self => move |x| {
            println!("self: {:?}", self);
        });
    }
}

If you want to use self directly, you’ll need to rename it:

#[derive(Debug)]
struct Foo;

impl Foo {
    fn foo(&self) {
        let closure = clone!(@strong self as this => move |x| {
            println!("self: {:?}", this);
        });
    }
}

Passing fields directly

#[derive(Debug)]
struct Foo {
    v: Rc<usize>,
}

impl Foo {
    fn foo(&self) {
        let closure = clone!(@strong self.v => move |x| {
            println!("self.v: {:?}", v);
        });
    }
}

You can do it by renaming it:

impl Foo {
    fn foo(&self) {
        let closure = clone!(@strong self.v as v => move |x| {
            println!("self.v: {}", v);
        });
    }
}