FFI::C::Util(3pm)

✨ FFI::C::Util ✨

okay bestie, welcome to FFI::C::Util — that's a section 3pm Perl module, and it is literally the utility belt for dealing with structured C data 💅

---

🌸 VERSION

version 0.15 — yes queen, that's the one 🎀

---

🦋 SYNOPSIS

use FFI::C::Util qw( perl_to_c take );
use FFI::C::StructDef;
use FFI::Platypus::Memory qw( free );

my $def = FFI::C::StructDef->new(
  members => [
    x => 'uint8',
    y => 'sint64',
  ],
);
my $inst = $def->create;

# initialize members
perl_to_c($inst, { x => 1, y => 2 });

# take ownership
my $ptr = take $inst;

# since we took ownership, we are responsible for freeing the memory:
free $ptr;

like… look at her go 😭✨

---

💖 DESCRIPTION

So this module is handing you some genuinely useful utility functions for dealing with the various def instances that FFI::C gives you. That's the whole vibe. No cap 🫶

---

👑 FUNCTIONS

🍓 perl_to_c

perl_to_c $instance, \%values;  # for Struct/Union
perl_to_c $instance, \@values;  # for Array

This one initializes the members of an instance for you. Struct/Union? Pass a hashref. Array? Pass an arrayref. Simple as, bestie 💅

---

🧚 c_to_perl

my $perl = c_to_perl $instance;

Hand it an instance, and it hands you back the nested members as good old Perl data structures. It's giving translator energy ✨

---

🎀 owned

my $bool = owned $instance;

Returns true if $instance owns its allocated memory — meaning it will free up that allocated memory when it falls out of scope. iconic behaviour 💖

Reasons an instance might not be owned:

• the instance is nested inside another object that owns the memory
• the instance was returned from a C function that owns the memory
• ownership was taken away by the take function below

so yeah, if owned says false, that memory is somebody else's problem, not yours 🙈

---

🔥 take

my $ptr = take $instance;

This function takes ownership of the instance pointer and returns the opaque pointer. And that means a couple of things, bestie, listen up:

• $instance will not free its data automatically
  • You should call free on it manually to free the memory it is using.
• $instance cannot be used anymore
  • So don't try to get/set any of its members, or pass it into a function.

⚠️ fr fr, once you take, that instance is done. touching it is not it.

The returned pointer can be cast into something else, or passed into a function that takes an opaque argument. slay 👑

---

🌈 addressof

[version 0.11]

my $ptr = addressof $instance;

This one returns the address (as an opaque type) of the instance object. It's similar to take above in that it gets you the address of the object — but it doesn't take ownership of it. So care needs to be taken when using $ptr that the object is still allocated 😭

⚠️ no ownership transferred here. you are borrowing, not keeping. keep that object alive or it's over 💀

---

⭐ set_array_count

set_array_count $inst, $count;

This sets the element count on a variable array returned from C — which, normally, there's literally no way to know just from the return value. So thank u for this one 🫶

⚠️ If you try to set a count on a non-array, or on a fixed sized array, an exception will be thrown. periodt.

---

🌟 SEE ALSO

• 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

go read the whole friend group, iykyk 💜

---

🦋 AUTHOR

Graham Ollis <plicease@cpan.org> — the main character who wrote all this 💅✨

---

💖 COPYRIGHT AND LICENSE

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 that's the whole page bestie, mwah 🫶 this was FFI::C::Util, perl v5.36.0, dated 2023-02-06, and honestly? iconic, no notes 💖✨🎀