FFI::C::Def(3pm)

📦 version 0.15, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 FFI::C::Def 💖

okay so bestie, welcome to FFI::C::Def — the Data definition for FFI. she's the mom of the whole fam, the blueprint era, the moment before the moment. also she's version 0.15 and she is not like other girls (other girls being, y'know, the subclasses).

✨ SYNOPSIS ✨

so first, in your C code (yes we're doing C today, stay with me):

#include <stdint.h>
#include <stdio.h>

typedef struct {
  uint8_t red;
  uint8_t green;
  uint8_t blue;
} color_t;

void
print_color(color_t *c)
{
  printf("[%02x %02x %02x]\n",
    c->red,
    c->green,
    c->blue
  );
}

and now the Perl side, where the actual slay happens:

use FFI::Platypus 1.00;
use FFI::C::StructDef;

my $ffi = FFI::Platypus->new( api => 1 );
# See FFI::Platypus::Bundle for how bundle works.
$ffi->bundle;

my $def = FFI::C::StructDef->new(
  $ffi,
  name  => 'color_t',
  class => 'Color',
  members => [
    red   => 'uint8',
    green => 'uint8',
    blue  => 'uint8',
  ],
);

my $red = Color->new({ red => 255 });

my $green = Color->new({ green => 255 });

$ffi->attach( print_color => ['color_t'] );

print_color($red);   # [ff 00 00]
print_color($green); # [00 ff 00]

# that red is a tad bright!
$red->red( 200 );

print_color($red);   # [c8 00 00]

like. look at her. colors from Perl to C and back. we're literally living in the future. 🦋

🌸 DESCRIPTION 🌸

okay so the tea: this class is the base class for all the def classes in the FFI::C collection. the def classes are the ones doing the defining of C struct, union and array types — and those types can be used from Perl and passed to C through FFI::Platypus. it's giving translator, it's giving bridge, it's giving diplomatic immunity. 💅

and listen — you do not create an instance of this class directly. no ma'am. you go through one of the subclasses:

  • FFI::C::StructDef
  • FFI::C::UnionDef
  • FFI::C::ArrayDef

this one is the parent, the ancestor, the lore. she stays home. 🎀

🧚 CONSTRUCTOR 🧚

new

my $def = FFI::C::StructDef->new(%opts);
my $def = FFI::C::StructDef->new($ffi, %opts);
my $def = FFI::C::UnionDef->new(%opts);
my $def = FFI::C::UnionDef->new($ffi, %opts);
my $def = FFI::C::ArrayDef->new(%opts);
my $def = FFI::C::ArrayDef->new($ffi, %opts);

okay so the constructor for this class shouldn't be invoked directly. like, if you try it, an exception will be thrown. she said don't touch, and she meant it. 🚫

for the subclasses tho: the first argument should be the FFI::Platypus instance you wanna use with the def. and if you don't provide one? no worries bestie, one will just be created internally for you. ✨

all the def classes accept these standard options:

  • name — the FFI::Platypus alias for this def. you can drop this name into function signatures when you're creating or attaching functions in FFI::Platypus. it's her government name.
  • class — the Perl class for this def. you can use that Perl class to create an instance of this def instead of invoking the create method down below. iconic behavior.
  • members — this is an array reference that specifies the member fields for the def. how it works exactly depends on the subclass, so go read the docs for whichever specific def class you're using. iykyk.
  • nullable — if it's true, then the type can be undef when it gets passed into C. undef gets translated to NULL. so like, the void is welcome here. 💀

👑 METHODS 👑

ffi

my $ffi = $def->ffi;

returns the FFI::Platypus instance used by this def. that's it. that's the method. 🫶

name

my $name = $def->name;

returns the FFI::Platypus alias for this def. this name can be used in function signatures when creating or attaching functions in FFI::Platypus. yes it's the same thing the name option sets, she's consistent, periodt.

class

my $class = $def->class;

returns the Perl class for this def — if one was specified. and that Perl class can be used to create an instance of this def instead of invoking the create method below. the circle of life fr fr. 🌈

size

my $size = $def->size;

returns the size of the def in bytes. numbers. we love numbers. ⭐

align

my $align = $def->align;

returns the alignment in bytes of the def. very demure, very mindful, very aligned. 🎀

nullable

my $bool = $def->nullable;

returns true if undef is allowed to be passed in to C functions. and remember: undef will be translated to NULL. no cap. 💅

create

my $instance = $def->create;
my $instance = $def->class->new;  # if class was specified

creates an instance of the def. baby's first def instance. she's born. 😭💖

🦋 SEE ALSO 🦋

the whole friend group, all of them, no one left out:

  • FFI::C
  • FFI::C::Array
  • FFI::C::ArrayDef
  • FFI::C::Def
  • FFI::C::File
  • FFI::C::PosixFile
  • FFI::C::Struct
  • FFI::C::StructDef
  • FFI::C::Union
  • FFI::C::UnionDef
  • FFI::C::Util
  • FFI::Platypus::Record

💜 AUTHOR 💜

Graham Ollis <plicease@cpan.org> — the actual icon, the blueprint, the one who wrote the whole thing. 🫶

This software is copyright (c) 2020-2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

okay bestie that's the whole page, no notes, ate and left no crumbs. 💅✨

signing off from perl v5.36.0, dated 2023-02-06, on the page they call FFI::C::Def(3pm) — love u, go define some structs 🦋💖🎀

📦 where this page comes from