Inline::Struct(3pm)

1Inline::Struct(3)     User Contributed Perl Documentation    Inline::Struct(3)
2
3
4

NAME

6       Inline::Struct -- Manipulate C structures directly from Perl.
7

SYNOPSIS

9         use Inline C => 'DATA', structs => ['Foo'];
10
11         my $obj = Inline::Struct::Foo->new;
12         $obj->num(10);
13         $obj->str("Hello");
14
15         print myfunc($obj), "\n";
16
17         __END__
18         __C__
19         struct Foo {
20           int num;
21           char *str;
22         };
23         typedef struct Foo Foo;
24
25         SV *myfunc(Foo *f) {
26           return newSVpvf("myfunc: num=%i, str='%s'", f->num, f->str);
27         }
28
29       This complete program prints:
30
31         myfunc: num=10, str='Hello'
32

DESCRIPTION

34       Inline::Struct is not a new language. It's a language extension
35       designed to be used by Inline::C. It parses struct definitions and
36       creates typemaps and XS code which bind each struct into a Perl class.
37       This code is passed to Inline::C, which compiles it in the normal way.
38
39       NOTE: Inline::Struct parses only C-style structs. It doesn't know about
40       any C++ extensions to structs like scopes, constructors or methods. If
41       you want such functionality you should use Inline::CPP to parse your
42       structs.
43

Using Inline::Struct

45       Inline::Struct has a Parse::RecDescent grammar to parse C structs. If a
46       struct is recognized, it can be bound to Perl. If the struct's
47       definition is not recognized (usually because it has a member with no
48       typemap), it will not be bound to Perl, but will be available from
49       other functions in C or C++.
50
51       The following example shows how a simple struct might look to a Perl
52       programmer.
53
54       Example 1:
55
56         use Inline C => <<'END', enable => 'structs';
57         struct Fraction {
58           long numer;
59           long denom;
60         };
61         END
62
63         my $o = Inline::Struct::Fraction->new(4, 3);
64         print $o->numer, $o->denom, "\n";
65         $o->numer(4)->denom(7);
66
67       After the code above has been compiled, Perl's namespace looks a lot
68       like the following:
69
70         package Inline::Struct::Fraction;
71         sub new { }
72         sub DESTROY { }
73         sub _KEYS { }
74         sub _VALUES { }
75         sub _HASH { }
76         sub numer { }
77         sub denom { }
78
79       Note that these are actually XS subs written in C, not Perl subs. But
80       that's what it looks like.
81

The Struct Interface

83       The following sections define the interface of each subroutine. Note:
84       this interface is likely to change in future versions of
85       Inline::Struct. Please don't rely on Inline::Struct in production code
86       quite yet.
87
88       When a struct is bound by Inline::Struct, a new namespace is created
89       underneath Inline::Struct. So if you have a struct named 'Foo', the
90       package of the Perl class will be 'Inline::Struct::Foo'.
91
92   new
93       If no arguments are provided, all fields are zeroed out. If you provide
94       values, they should be appropriate for the field type, and in the same
95       order as they are defined in the struct.
96
97   DESTROY
98       The destructor. Should never be called by the programmer -- this is
99       called automatically when the Perl variable holding the struct is
100       destroyed. Frees the memory associated with the struct. If the struct
101       holds pointers to malloc'd memory, they will not be freed. If you run
102       into such a situation, consider using C++ and Inline::CPP instead.
103
104   _KEYS
105       A read-only method, this returns a reference to an array containing the
106       names of the fields in the struct. The fields are in the order they
107       appear in the C source code.
108
109   _VALUES
110       A read-only method, this returns a reference to an array containing the
111       values of the fields in the struct. The values are returned in the same
112       order as the fields.
113
114   _HASH
115       A read-only method, this returns a reference to a hash, mapping field
116       names to field values.
117
118   Accessors
119       For each field in the struct, an accessor method will be created which
120       lets you get or set the value in the struct. If no arguments are
121       provided, the method returns the value of that field. If any arguments
122       are provided, the field is set to the first argument, and the modified
123       structure is returned. This makes setting multiple fields easy:
124
125          $o->field1(something)->field2(somethingelse);
126

C and C++ Configuration Options

128       Inline::Struct has no configuration options of its own, but it does
129       provide a new configuration option for C or C++.
130
131   structs
132       Specifies that structs are to be bound to Perl. There are several
133       meanings to this option, so I'll explain with an example:
134
135          use Inline C => config => structs => 'Foo';
136
137       Adds 'Foo' to the list of structs to bind to Perl.
138
139          use Inline C => config => structs => ['Foo', 'Bar'];
140
141       Adds 'Foo' and 'Bar' to the list of structs to bind to Perl.
142
143          use Inline C => config => structs => undef;
144
145       Clears the list of structs to bind to Perl.
146
147          use Inline C => config => enable => 'structs';
148       or
149          use Inline C => config => structs => 1;
150
151       Enable binding structs to Perl, without specifying any structs to
152       search for.  As shown, this would bind all structs to Perl.
153
154          use Inline C => config => disable => 'structs';
155
156       or
157
158          use Inline C => config => structs => 0;
159
160       Disable binding structs to Perl.
161

PERFORMANCE OF STRUCTS AGAINST PERL DATA STRUCTURES

163   Time
164       A script, benchmark, that benchmarks a simple C "struct" against a
165       pure-Perl data structure, is supplied. It should be run a couple of
166       times to get everything cached. A typical results run is as follows:
167
168         Faster type          % faster
169         ISF dnum read        24%
170         PP dnum write        247%
171         ISF inum read        39%
172         PP inum write        231%
173         ISF str read         18%
174         PP str write         264%
175
176       This shows that reading the struct is faster than a simple object
177       implemented as a hash-ref, while writing to a struct in the current
178       implementation is several times slower. If the Perl object is instead
179       implemented as an array-ref, in the class "PP::Foo::Array", the numbers
180       do not change significantly.
181
182   Memory
183       The same script also compares memory usage. A typical results run:
184
185         Memory usage
186         10000 x bless [ 7, "string" ], "main": 34592
187         10000 x Inline::Struct::Foo->new: 45648
188         100000 x bless [ 7, "string" ], "main": 139344
189         100000 x Inline::Struct::Foo->new: 248080
190         1000000 x bless [ 7, "string" ], "main": 1187024
191         1000000 x Inline::Struct::Foo->new: 2257968
192
193       The memory usage of the struct is around twice as large.
194

AUTHOR

200       Neil Watkiss (NEILW@cpan.org)
201

COPYRIGHT

203       Copyright (C) 2001, Neil Watkiss.
204
205       This module is free software. It may be used, redistributed and/or
206       modified under the same terms as Perl itself.
207
208       See <http://dev.perl.org/licenses/>
209
210
211
212perl v5.34.0                      2021-07-22                 Inline::Struct(3)