Skip to content
Browse files

MemPtr.pm: add FFI::Raw::MemPtr docs

  • Loading branch information...
1 parent c968b75 commit 4917087f593c42c0df62a7739f3e9711d49f8d8d @ghedo committed Feb 11, 2013
Showing with 78 additions and 4 deletions.
  1. +2 −4 lib/FFI/Raw.pm
  2. +76 −0 lib/FFI/Raw/MemPtr.pm
View
6 lib/FFI/Raw.pm
@@ -77,10 +77,8 @@ This works becasue FFI::Raw overloads the C<&{}> operator.
=head2 memptr( $number )
-Allocate C<$number> bytes and return a C<FFI::Raw::MemPtr> pointing to the
-allocated memory. This can be passed to functions which take a C<FFI::Raw::ptr>
-argument. A C<FFI::Raw::MemPtr> can be converted to a Perl string using the
-C<tostr()> method.
+Allocate C<$number> bytes and return a L<FFI::Raw::MemPtr> pointing to the
+allocated memory. This is a shortcut for C<FFI::Raw::MemPtr -> new(...)>.
=cut
View
76 lib/FFI/Raw/MemPtr.pm
@@ -0,0 +1,76 @@
+package FFI::Raw::MemPtr;
+
+use strict;
+use warnings;
+
+=head1 NAME
+
+FFI::Raw::MemPtr - FFI::Raw memory pointer type
+
+=head1 DESCRIPTION
+
+A B<FFI::Raw::MemPtr> represents a memory pointer which can be passed to
+functions taking a C<FFI::Raw::ptr> argument.
+
+=head1 METHODS
+
+=head2 new( $number )
+
+Allocate a new C<FFI::Raw::MemPtr> of size C<$number> bytes.
+
+=head2 new_from_buf( $buffer, $number )
+
+Allocate a new C<FFI::Raw::MemPtr> of size C<$number> bytes and copy C<$buffer>
+into it. This can be used, for example, to pass a pointer to a function that
+takes a C struct pointer, by using C<pack()> or the L<Convert::Binary::C> module
+to create the actual struct content.
+
+For example, consider a C function:
+
+ struct some_struct {
+ int some_int;
+ char some_str[];
+ };
+
+ extern void take_one_struct(struct some_struct *arg) {
+ if (arg -> some_int == 42)
+ puts(arg -> some_str);
+ }
+
+It can be called using FFI::Raw as follows:
+
+ use FFI::Raw;
+
+ my $struct = pack('iZ', 42, 'hello');
+ my $arg = FFI::Raw::MemPtr -> new_from_buf($packed, 13);
+
+ my $take_one_struct = FFI::Raw -> new(
+ $shared, 'take_one_struct',
+ FFI::Raw::void, FFI::Raw::ptr
+ );
+
+ $take_one_struct -> ($arg);
+
+Which would print C<hello>.
+
+=head2 tostr( )
+
+Convert a C<FFI::Raw::MemPtr> to a Perl string.
+
+=head1 AUTHOR
+
+Alessandro Ghedini <alexbio@cpan.org>
+
+=head1 LICENSE AND COPYRIGHT
+
+Copyright 2013 Alessandro Ghedini.
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of either: the GNU General Public License as published
+by the Free Software Foundation; or the Artistic License.
+
+See http://dev.perl.org/licenses/ for more information.
+
+=cut
+
+1; # End of FFI::Raw::MemPtr

0 comments on commit 4917087

Please sign in to comment.
Something went wrong with that request. Please try again.