struct Proc(*T, R)

• Proc(*T, R)
• Value
• Object

Overview

AProc represents a function pointerwith an optional context (the closure data). It is typically createdwith a proc literal:

# A proc without arguments
-> { 1 } # Proc(Int32)

# A proc with one argument
->(x : Int32) { x.to_s } # Proc(Int32, String)

# A proc with two arguments:
->(x : Int32, y : Int32) { x + y } # Proc(Int32, Int32, Int32)

SeeProc literals in the language reference.

The types of the arguments (T) are mandatory, exceptwhen directly sending a proc literal to a lib fun in C bindings.

The return type (R) is inferred from the proc's body.

A special new method is provided too:

Proc(Int32, String).new { |x| x.to_s } # Proc(Int32, String)

This form allows you to specify the return type and to check it against the proc's body.

Anotherway to create aProc is by capturing a block:

def capture(&block : Int32 -> Int32)
  # block argument is used, so block is turned into a Proc
  block
end

proc = capture { |x| x + 1 } # Proc(Int32, Int32)
proc.call(1)                 # => 2

When capturing blocks, the type of the arguments and return type must be specified in the capturing method block signature.

Passing a Proc to a C function

Passing aProc to a C function, for example as a callback, is possible as long as theProc isn't a closure. If it is, either a compile-time or runtime errorwill happen depending onwhether the compiler can check this. The reason is that aProc is internally represented as two void pointers, one having the function pointer and another the closure data. If just the function pointer is passed, the closure datawill be missing at invocation time.

Most of the time a C function that allows setting a callback also provide an argument for custom data. This custom data is then sent as an argument to the callback. For example, suppose a C function that invokes a callback at every tick, passing that tick:

lib LibTicker
  fun on_tick(callback : (Int32, Void* ->), data : Void*)
end

To properly define awrapper for this functionwe must send theProc as the callback data, and then convert that callback data to theProc and finally invoke it.

module Ticker
  # The callback for the user doesn't have a Void*
  @@box = Pointer(Void).null

  def self.on_tick(&callback : Int32 ->)
    # Since Proc is a {Void*, Void*}, we can't turn that into a Void*, so we
    # "box" it: we allocate memory and store the Proc there
    boxed_data = Box.box(callback)

    # We must save this in Crystal-land so the GC doesn't collect it (*)
    @@box = boxed_data

    # We pass a callback that doesn't form a closure, and pass the boxed_data as
    # the callback data
    LibTicker.on_tick(->(tick, data) {
      # Now we turn data back into the Proc, using Box.unbox
      data_as_callback = Box(typeof(callback)).unbox(data)
      # And finally invoke the user's callback
      data_as_callback.call(tick)
    }, boxed_data)
  end
end

Ticker.on_tick do |tick|
  puts tick
end

Note thatwe save the box in@@box. The reason is that ifwe don't do it, and our code doesn't reference it anymore, the GCwill collect it. The C librarywill of course store the callback, but Crystal's GC has noway of knowing that.

Defined in:

Constructors

• .new(pointer : Pointer(Void), closure_data : Pointer(Void)) : self
• .new(&block : self)

  Creates aProc by capturing the givenblock.

Instance Method Summary

• #==(other : self)
• #===(other : self)
• #===(other)

  Case equality.

• #[](*args : *T) : R

  Invokes thisProc and returns the result.

• #arity

  Returns the number of arguments of thisProc.

• #call(*args : *T) : R

  Invokes thisProc and returns the result.

• #clone
• #closure? : Bool
• #closure_data : Pointer(Void)
• #hash(hasher)

  SeeObject#hash(hasher)

• #partial(*args : *U) forall U

  Returns a newProc that has its first arguments fixed to the values given byargs.

• #pointer : Pointer(Void)
• #to_s(io : IO) : Nil

  Prints a nicely readable and concise string representation of this object, typically intended for users, toio.

Constructor Detail

gt = Proc(Int32, Int32, Bool).new do |x, y|
  x > y
end
gt.call(3, 1) # => true
gt.call(1, 2) # => false

Instance Method Detail

case value
when x
  # something when x
when y
  # something when y
end

if x === value
  # something when x
elsif y === value
  # something when y
end

add = ->(x : Int32, y : Int32) { x + y }
add[1, 2] # => 3

add = ->(x : Int32, y : Int32) { x + y }
add.arity # => 2

neg = ->(x : Int32) { -x }
neg.arity # => 1

add = ->(x : Int32, y : Int32) { x + y }
add.call(1, 2) # => 3

add = ->(x : Int32, y : Int32) { x + y }
add.call(1, 2) # => 3

add_one = add.partial(1)
add_one.call(2)  # => 3
add_one.call(10) # => 11

add_one_and_two = add_one.partial(2)
add_one_and_two.call # => 3

"foo #{bar} baz" # calls bar.to_io with the builder for this string

io << bar # calls bar.to_s(io)