Skip to content
This repository
Newer
Older
100644 336 lines (218 sloc) 10.378 kb
8bffd5b3 » Whiteknight
2011-01-07 add in a new version of the embed docs, for the new API that doesn't …
1 # Copyright (C) 2001-2010, Parrot Foundation.
2
3 =head1 NAME
4
5 embed.pod - Parrot embedding system overview
6
7 =head1 SYNOPSIS
8
9 #include "parrot/api.h"
10
11 int main(int argc, char* argv[])
12 {
13 Parrot_PMC interp = NULL;
14 Parrot_PMC pf = NULL;
15 Parrot_PMC args = NULL;
16
17 if (!Parrot_api_make_interpreter(NULL, NULL, 0, &interp)) {
18 fprintf(stderr, "Cannot create Parrot interpreter!\n");
19 return 1;
20 }
21
22 if (!Parrot_api_load_bytecode_file(interp, "foo.pbc", &pf)
23 show_last_error_and_exit(interp);
24
25 if (!Parrot_api_pmc_wrap_string_array(interp, argc, argv, &args))
26 show_last_error_and_exit(interp);
27
28 if (!Parrot_api_run_bytecode(interp, pf, args))
29 show_last_error_and_exit(interp);
30
31 Parrot_api_destroy_interpreter(interp);
32 exit(EXIT_SUCCESS);
33 }
34
35 static void
36 show_last_error_and_exit(Parrot_PMC interp)
37 {
38 ASSERT_ARGS(show_last_error_and_exit)
39 Parrot_String errmsg, backtrace;
40 Parrot_Int exit_code, is_error;
41 Parrot_PMC exception;
42
43 if (!Parrot_api_get_result(interp, &is_error, &exception, &exit_code, &errmsg))
44 exit(EXIT_FAILURE);
45 if (is_error) {
46 if (!Parrot_api_get_exception_backtrace(interp, exception, &backtrace))
47 exit(EXIT_FAILURE);
48 print_parrot_string(interp, stderr, errmsg, 1);
49 print_parrot_string(interp, stderr, backtrace, 0);
50 }
51
52 exit(exit_code);
53 }
54
55 static void
56 print_parrot_string(Parrot_PMC interp, ARGMOD(FILE *vector), Parrot_String str,
57 int newline)
58 {
59 ASSERT_ARGS(print_parrot_string)
60 char * msg_raw;
61 if (!str)
62 return;
63 Parrot_api_string_export_ascii(interp, str, &msg_raw);
64 if (msg_raw) {
65 fprintf(vector, "%s%s", msg_raw, newline ? "\n" : "");
66 Parrot_api_string_free_exported_ascii(interp, msg_raw);
67 }
68 }
69
70 =head1 FILES
71
72 =over 4
73
74 =item F<include/parrot/api.h>
75
76 =back
77
78 =head1 DESCRIPTION
79
80 This is the documentation for Parrot's embedding API.
81
82 =head2 Overview
83
84 Parrot defines a strict embedding API. This API may only be used by embedding
85 applications, and other functions exported by libparrot may not be used at
86 the same time. All embedding API functions are named C<Parrot_api_*> and are
87 located in the file F<include/parrot/api.h>. No other header files are
88 necessary or permissible for embedding applications.
89
90 All embedding API functions return an integer status code: C<0> on failure
91 and C<1> on success. If a failure code is returned, other API calls can be
92 made to retrieve the error object and then query information from it.
93
94 =head2 Data structures
95
96 The embedding API makes use of very few core data types.
97
98 =over 4
99
100 =item C<Parrot_String>
101
102 Parrot's internal string type, which contains character encoding information.
103
104 =item C<Parrot_PMC>
105
106 A Polymorphic Container object. This is the opaque external type for (PMC *).
107 PMCs represent any object more complicated than a primitive string or number
108 type, and can also provide high-level wrappers around primitive types.
109
110 =item C<Parrot_Int>
111
112 Parrot's integer numeric type.
113
114 =item C<Parrot_Float>
115
116 Parrot's floating point numeric type.
117
118 =back
119
120 =head2 Function signatures
121
122 What is a function signature? It is a string which represents the calling and
123 return conventions of a function. It is a very succinct representation of the
124 answer to the question "How do I call this function and what does it
125 return?".
126
127 All function signatures follow the form of:
128
129 Foo->Bar
130
131 where C<Foo> and C<Bar> are a list of zero or more Parrot datatypes. C<Foo>
132 and C<Bar> are individually called 'type signatures'. The datatypes on the
133 left of the arrow are function arguments being passed in and the datatypes on
134 the right are the datatype being returned. No spaces are allowed in a
135 function signature.
136
137 There are four datatypes that can be used in Parrot function signatures:
138
139 I <=> Parrot_Int
140 N <=> Parrot_Float (Numeric)
141 S <=> Parrot_String
142 P <=> Parrot_PMC
143
144 Here are some example function signatures and what they mean:
145
146 INN->N In: Integer, two Numerics Out: Numeric
147 SIN->S In: String, Integer, Numeric Out: String
148 P->S In: PMC Out: String
149 PiP->S In: PMC (method call) Out: String
150 NN->N In: Two Numerics Out: Numeric
151 I->I In: Integer Out: Integer
152 I->N In: Integer Out: Numeric
153 N->P In: Numeric Out: PMC
154 Pi-> In: none (method call) Out: none
155 ->I In: none Out: Integer
156 -> In: none Out: none
157
158 Parrot functions support an unlimited number of function inputs and outputs.
159
160 In addition to the basic signature elements shown above, lower-case letters
161 may be used to modify some types of inputs and outputs:
162
163 Pi -> the invocant for a method call. Pi must be the first argument, if it
164 is to be used.
165 Pf -> The PMC is an aggregate (Hash, Array). The elements of the PMC will
166 be separated out and will be passed individually.
167 Sn -> The String is the name of the previous argument, which is passed by
168 name, not by position.
169
170 Parrot function signature strings are used when a Parrot function or method
171 call needs to be made.
172
173 =head2 Interpreter initialization and destruction
174
175 =over 4
176
177 =item C<Parrot_Int Parrot_api_make_interpreter(parent, init, flags, &interp)>
178
179 Creates a new interpreter, with optional initialization information and
180 creation flags. The intepreter will have a child/parent relationship with
181 C<parent>, if provided. The returned interpreter object is itself a PMC, and
182 can be operated on like any other PMC if desired.
183
184 =item C<Parrot_Int Parrot_api_set_executable_name(interp, name)>
185
186 Sets the executable name of the calling process.
187
188 =item C<Parrot_Int Parrot_api_destroy_interpreter(interp)>
189
190 Destroys an interpreter. After this call is made, the interpreter and all
191 PMC and STRING objects created from it are dead and cannot be used.
192
193 =back
194
195 =head2 Loading and running bytecode
196
197 =over 4
198
199 =item C<Parrot_Int Parrot_api_load_bytecode(interp, path, &pbc)>
200
201 Reads Parrot bytecode (.pbc) file from the specified location and returns it
202 as a PMC.
203
204 =item C<Parrot_Int Parrot_api_ready_bytecode(interp, pbc, &main)>
205
206 Loads a PBC PMC into the interpreter but does not run it. It returns a
207 reference to the :main Sub PMC, if one is available. This causes any :load
208 Sub PMCs to be executed.
209
210 =item C<Parrot_Int Parrot_api_run_bytecode(interp, pbc, args)>
211
212 Loads and executes the given bytecode, executing any :init Sub PMCs, and then
213 the :main Sub with the given arguments.
214
215 =back
216
217 =head2 Data manipulation
218
219 =head3 Native types
220
221 =over 4
222
223 =item C<Parrot_Int Parrot_api_string_export_ascii(interp, pstring, &cstring)>
224
225 =item C<Parrot_Int Parrot_api_string_export_wchar(interp, pstring, &cstring)>
226
227 Returns the char* or wchar_t* representation of the Parrot string. An exported
228 string must be explicitly freed to prevent memory leaks.
229
230 =item C<Parrot_Int Parrot_api_string_free_exported_ascii(interp, cstring)>
231
232 =item C<Parrot_Int Parrot_api_string_free_exported_wchar(interp, cstring)>
233
234 Free's a char* or wchar_t* which has been exported.
235
236 =item C<Parrot_Int Parrot_api_string_import_ascii(interp, cstring, &pstring)>
237
238 =item C<Parrot_Int Parrot_api_string_import_wchar(interp, cstring, &pstring)>
239
240 Converts a native char* or wchar_t* string into a Parrot_String.
241
242 =item C<Parrot_Int Parrot_api_string_import_binary(interp, bytes, length, &pstring)>
243
244 Imports an unsigned char* array of bytes. It is not treated like a normal C
245 string, and is not expected to be null-terminated.
246
247 =back
248
249 =head3 PMCs
250
251 =over 4
252
253 =item C<Parrot_Int Parrot_api_pmc_wrap_string_array(interp, argc, argv, &args)>
254
255 Wraps a char** string array into a string array PMC
256
257 =item C<Parrot_Int Parrot_api_pmc_box_string(interp, pstring, &pmc)>
258
259 Creates a new PMC to wrap a Parrot_String.
260
261 =item C<Parrot_Int Parrot_api_pmc_get_class(interp, key, &class)>
262
263 Retrieves a Class PMC using a key PMC. The key can be a string, or a string
264 array PMC.
265
266 =item C<Parrot_Int Parrot_api_new_from_class(interp, class, init, &pmc)>
267
268 Instantiates a new PMC from it's class object.
269
270 =item C<void Parrot_api_pmc_keep_alive(interp, pmc, alive)>
271
272 If C<alive> is 1, the PMC becomes immortal and cannot be collected by Parrot's
273 GC. Do this if the PMC is still being used, but is not reachable by Parrot's
274 GC. This would be the case if the PMC reference were passed to an external
275 library. If C<alive> is 0, the PMC becomes mortal again and can be collected
276 like normal if it is found to be unreachable.
277
278 =back
279
280 =head2 Calling subroutines and Methods
281
282 =over 4
283
017e3b79 » mstevens
2011-02-18 fix some warnings from podchecker
284 =item *
285
8bffd5b3 » Whiteknight
2011-01-07 add in a new version of the embed docs, for the new API that doesn't …
286 TODO
287
288 =back
289
290 =head1 COMPILING
291
292 Note: This section is aimed at you if you are writing an application
293 external to parrot which links against an installed parrot library.
294
295 =head2 Compiler and linker flags
296
297 Your application will need to include the appropriate header files and
298 link against parrot and its dependencies.
299
300 Because the location of these files can vary from platform to platform, and
301 build to build, a general method is provided to find out the necessary flags to
302 use.
303
304 C<parrot_config> is the helper tool for determining anything related to parrot
305 configuration, determining compiler and linker flags to build against parrot is
306 no different.
307
308 To start, you should find C<parrot_config> in the path or allow your user to
309 provide this location for you. You can check this by running C<parrot_config> with
310 C<VERSION> as the argument to determine the version of parrot you are working with.
311
312 To determine the necessary C compiler flags, use C<embed-cflags>:
313
314 parrot_config embed-cflags
315
316 ... and to find the necessary linker flags, use C<embed-ldflags>:
317
318 parrot_config embed-ldflags
319
320 The C<parrot_config> command can be incorporated with a compile as shown here
321 performing both compiling and linking in one step.
322
323 cc src/disassemble.c `parrot_config embed-cflags` `parrot_config embed-ldflags`
324
325 =head1 EXAMPLES
326
327 =head2 Load bytecode as a library and run a single subroutine
328
329 TODO
017e3b79 » mstevens
2011-02-18 fix some warnings from podchecker
330
8bffd5b3 » Whiteknight
2011-01-07 add in a new version of the embed docs, for the new API that doesn't …
331 =head1 SEE ALSO
332
333 F<frontend/parrot/main.c> and F<t/src/embed/*.t> for Parrot's use of the
334 embedding system.
335
336 =cut
Something went wrong with that request. Please try again.