Struct RcBlock

Source

pub struct RcBlock<F: ?Sized> { /* private fields */ }

Expand description

A reference-counted Objective-C block that is stored on the heap.

This is a smart pointer that Derefs to Block.

The generic type F must be a dyn Fn that implements the BlockFn trait, just like described in Block’s documentation.

§Memory-layout

This is guaranteed to have the same size and alignment as a pointer to a block (i.e. same size as *const Block<A, R>).

Additionally, it participates in the null-pointer optimization, that is, Option<RcBlock<A, R>> is guaranteed to have the same size as RcBlock<A, R>.

Implementations§

Source §

impl<F: ?Sized> RcBlock<F>

Source

pub fn as_ptr(this: &Self) -> *mut Block<F>

A raw pointer to the underlying block.

The pointer is valid for at least as long as the RcBlock is alive.

This is an associated method, and must be called as RcBlock::as_ptr(&block).

Source

pub fn into_raw(this: Self) -> *mut Block<F>

Consumes the RcBlock, passing ownership of the retain count to the caller.

After calling this function, the caller is responsible for releasing the memory with ffi::_Block_release or similar.

This is an associated method, and must be called as RcBlock::into_raw(block).

§Examples

Converting a RcBlock to a pointer and back.

use block2::RcBlock;

let add2 = RcBlock::new(|x: i32| -> i32 {
    x + 2
});
let ptr = RcBlock::into_raw(add2);
// SAFETY: The pointer is valid, and ownership from above.
let add2 = unsafe { RcBlock::from_raw(ptr) }.unwrap();

Source

pub unsafe fn from_raw(ptr: *mut Block<F>) -> Option<Self>

Construct an RcBlock from the given block pointer by taking ownership.

This will return None if the pointer is NULL.

§Safety

The given pointer must point to a valid block, the parameter and return types must be correct, and the block must have a +1 reference / retain count from somewhere else.

Additionally, the block must be safe to call (or, if it is not, then you must treat every call to the block as unsafe).

Source

pub unsafe fn copy(ptr: *mut Block<F>) -> Option<Self>

Construct an RcBlock from the given block pointer.

The block will be copied, and have its reference-count increased by one.

This will return None if the pointer is NULL, or if an allocation failure occurred.

See Block::copy for a safe alternative when you already know the block pointer is valid.

§Safety

The given pointer must point to a valid block, and the parameter and return types must be correct.

Additionally, the block must be safe to call (or, if it is not, then you must treat every call to the block as unsafe).

Source §

impl<F: ?Sized> RcBlock<F>

Source

pub fn new<'f, A, R, Closure>(closure: Closure) -> Self
where A: EncodeArguments, R: EncodeReturn, Closure: IntoBlock<'f, A, R, Dyn = F>,

Construct a RcBlock with the given closure.

The closure will be coped to the heap on construction.

When the block is called, it will return the value that results from calling the closure.

Source

pub fn with_encoding<'f, A, R, Closure, E>(closure: Closure) -> Self
where A: EncodeArguments, R: EncodeReturn, Closure: IntoBlock<'f, A, R, Dyn = F>, E: ManualBlockEncoding<Arguments = A, Return = R>,

Constructs a new RcBlock with the given function and encoding information.

See StackBlock::with_encoding as to why and how this could be useful. The same requirements as Self::new apply here as well.

§Example

struct MyBlockEncoding;
// SAFETY: The encoding is correct.
unsafe impl ManualBlockEncoding for MyBlockEncoding {
    type Arguments = (*mut NSError,);
    type Return = i32;
    const ENCODING_CSTR: &'static CStr = if cfg!(target_pointer_width = "64") {
        cr#"i16@?0@"NSError"8"#
    } else {
        cr#"i8@?0@"NSError"4"#
    };
}

let my_block = RcBlock::with_encoding::<_, _, _, MyBlockEncoding>(|_err: *mut NSError| {
    42i32
});
assert_eq!(my_block.call((core::ptr::null_mut(),)), 42);

Methods from Deref<Target = Block<F>>§

Source

pub fn copy(&self) -> RcBlock<F>

Copy the block onto the heap as an RcBlock.

The behaviour of this function depends on whether the block is from a RcBlock or a StackBlock. In the former case, it will bump the reference-count (just as-if you’d Clone’d the RcBlock), in the latter case it will construct a new RcBlock from the StackBlock.

This distinction should not matter, except for micro-optimizations.

Source