Benjamin Otte
2007-Jun-29 00:01 UTC
[Swfdec] Branch 'as' - 3 commits - doc/Makefile.am doc/swfdec-docs.sgml doc/swfdec-sections.txt libswfdec/swfdec_as_context.c libswfdec/swfdec_as_context.h
doc/Makefile.am | 1 doc/swfdec-docs.sgml | 2 doc/swfdec-sections.txt | 39 +++++++++++ libswfdec/swfdec_as_context.c | 139 +++++++++++++++++++++++++++++++++++------- libswfdec/swfdec_as_context.h | 5 - 5 files changed, 160 insertions(+), 26 deletions(-) New commits: diff-tree 2203783339a0ece4ce8d264d0ec28c77034c3288 (from bc23ec80d8afa3d49618a6b180ace50f7c7b19f3) Author: Benjamin Otte <otte at gnome.org> Date: Fri Jun 29 02:00:55 2007 +0200 add an internals/garbage collection section and a stub for documenting SwfdecAsContext diff --git a/doc/Makefile.am b/doc/Makefile.am index f43e706..ce3ae3a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -56,6 +56,7 @@ IGNORE_HFILES= \ jpeg \ swfdec_amf.h \ swfdec_as_interpret.h \ + swfdec_as_math.h \ swfdec_as_number.h \ swfdec_as_string.h \ swfdec_as_strings.h \ diff --git a/doc/swfdec-docs.sgml b/doc/swfdec-docs.sgml index 07c7ee4..537817a 100644 --- a/doc/swfdec-docs.sgml +++ b/doc/swfdec-docs.sgml @@ -22,6 +22,8 @@ </chapter> <chapter> <title>Actionscript interpreter</title> + <xi:include href="xml/Internals.xml"/> <xi:include href="xml/SwfdecAsValue.xml"/> + <xi:include href="xml/SwfdecAsContext.xml"/> </chapter> </book> diff --git a/doc/swfdec-sections.txt b/doc/swfdec-sections.txt index 4d93f11..d147bdd 100644 --- a/doc/swfdec-sections.txt +++ b/doc/swfdec-sections.txt @@ -180,6 +180,14 @@ SWFDEC_TYPE_GTK_LOADER </SECTION> <SECTION> +<FILE>Internals</FILE> +<TITLE>Internals</TITLE> +swfdec_as_object_mark +swfdec_as_string_mark +swfdec_as_value_mark +</SECTION> + +<SECTION> <FILE>SwfdecAsValue</FILE> <TITLE>SwfdecAsValue</TITLE> SwfdecAsValueType @@ -212,3 +220,34 @@ SWFDEC_AS_VALUE_IS_STRING SWFDEC_AS_VALUE_IS_NULL SWFDEC_AS_VALUE_IS_OBJECT </SECTION> + +<SECTION> +<FILE>SwfdecAsContext</FILE> +<TITLE>SwfdecAsContext</TITLE> +swfdec_as_context_abort +swfdec_as_context_abort_oom +swfdec_as_context_eval +swfdec_as_context_eval_set +swfdec_as_context_gc +swfdec_as_context_get_string +swfdec_as_context_get_time +swfdec_as_context_give_string +swfdec_as_context_maybe_gc +swfdec_as_context_new +swfdec_as_context_return +swfdec_as_context_run +swfdec_as_context_startup +swfdec_as_context_trace +swfdec_as_context_unuse_mem +swfdec_as_context_use_mem +<SUBSECTION Standard> +swfdec_as_context_get_type +SwfdecAsContextClass +SWFDEC_AS_CONTEXT +SWFDEC_AS_CONTEXT_CLASS +SWFDEC_AS_CONTEXT_GET_CLASS +SWFDEC_IS_AS_CONTEXT +SWFDEC_IS_AS_CONTEXT_CLASS +SWFDEC_TYPE_AS_CONTEXT +</SECTION> + diff-tree bc23ec80d8afa3d49618a6b180ace50f7c7b19f3 (from 677831ce294814177191a5950e5320efb73d6e3d) Author: Benjamin Otte <otte at gnome.org> Date: Fri Jun 29 02:00:34 2007 +0200 add lots of documentation diff --git a/libswfdec/swfdec_as_context.c b/libswfdec/swfdec_as_context.c index 8e06f31..0037932 100644 --- a/libswfdec/swfdec_as_context.c +++ b/libswfdec/swfdec_as_context.c @@ -38,7 +38,71 @@ #include "swfdec_debug.h" #include "swfdec_script.h" -/*** GTK_DOC ***/ +/*** GARBAGE COLLECTION DOCS ***/ + +/** + * SECTION:Internals + * @title: Internals and garbage collection + * @short_description: understanding internals such as garbage collection + * @see_also: #SwfdecAsContext + * + * This section deals with the internals of the Swfdec Actionscript engine. You + * should probably read this first when trying to write code with it. If you're + * just trying to use Swfdec for creating Flash content, you can probably skip + * this section. + * + * First, I'd like to note that the Swfdec script engine has to be modeled very + * closely after the existing Flash players. So if there are some behaviours + * that seem stupid at first sight, it might very well be that it was chosen for + * a very particular reason. Now on to the features. + * + * The Swfdec script engine tries to imitate Actionscript as good as possible. + * Actionscript is similar to Javascript, but not equal. Depending on the + * version of the script executed it might be more or less similar. An important + * example is that Flash in versions up to 6 did case-insensitive variable + * lookups. + * + * The script engine starts its life when it is initialized via + * swfdec_as_context_startup (). At that point, the basic objects are created. + * After this function has been called, you can start executing code. All code + * execution happens by creating a new #SwfdecAsFrame and then calling + * swfdec_as_context_run () to execute it. This function is the single entry + * point for code execution. Convenience functions exist that make executing + * code easy, most notably swfdec_as_object_run() and + * swfdec_as_object_call(). + * + * It is also easily possible to extend the environment by adding new objects. + * In fact, without doing so, the environment is pretty bare as it just contains + * the basic Math, String, Number, Array, Date and Boolean objects. This is done + * by adding #SwfdecAsNative functions to the environment. The easy way + * to do this is via swfdec_as_object_add_function(). + * + * The Swfdec script engine is dynamically typed and knows about different types + * of values. See #SwfdecAsValue for the different values. Memory management is + * done using a mark and sweep garbage collector. You can initiate a garbage + * collection cycle by calling swfdec_as_context_gc() or + * swfdec_as_context_maybe_gc(). You should do this regularly to avoid excessive + * memory use. The #SwfdecAsContext will then collect the objects and strings it + * is keeping track of. If you want to use an object or string in the script + * engine, you'll have to add it first via swfdec_as_object_add() or + * swfdec_as_context_get_string() and swfdec_as_context_give_string(), + * respectively. + * + * Garbage-collected strings are special in Swfdec in that they are unique. This + * means the same string exists exactly once. Because of this you can do + * equality comparisons using == instead of strcmp. It also means that if you + * forget to add a string to the context before using it, your app will most + * likely not work, since the string will not compare equal to any other string. + * + * When a garbage collection cycle happens, all reachable objects and strings + * are marked and all unreachable ones are freed. This is done by calling the + * context class's mark function which will mark all reachable objects. This is + * usually called the "root set". For any reachable object, the object's mark + * function is called so that the object in turn can mark all objects it can + * reach itself. Marking is done via functions described below. + */ + +/*** GTK-DOC ***/ /** * SwfdecAsContextState @@ -58,6 +122,15 @@ /*** RUNNING STATE ***/ +/** + * swfdec_as_context_abort: + * @context: a #SwfdecAsContext + * @reason: a string describing why execution was aborted + * + * Aborts script execution in @context. Call this functon if the script engine + * encountered a fatal error and cannot continue. A possible reason for this is + * an out-of-memory condition. + **/ void swfdec_as_context_abort (SwfdecAsContext *context, const char *reason) { @@ -78,22 +151,8 @@ swfdec_as_context_abort (SwfdecAsContext * * Registers @bytes additional bytes as in use by the @context. This function * keeps track of the memory that script code consumes. If too many memory is - * in use, this function may decide to abort execution with an out of memory - * error. It may also invoke the garbage collector to free unused memory. Note - * that running the garbage collector is a potentially dangerous operation, - * since the calling code must ensure that all memory is reachable for the - * garbage collector. Consider the following innocent looking code: - * <informalexample><programlisting>SwfdecAsValue *v = swfdec_as_stack_pop (stack); - * SwfdecAsObject *object = swfdec_as_object_new (context); - * swfdec_as_object_set (object, swfdec_as_context_get_string (context, "something"), v); - * </programlisting></informalexample> - * This code may cause the value stored in v to be lost, as it is not reachable - * when swfdec_as_object_new() invokes the garbage collector. Because of this, - * all functions in the Actionscript engine that might invoke the garbage - * collector contain this warning: - * <warning>This function may run the garbage collector.</warning> - * All memory allocated with this function must be released with - * swfdec_as_context_unuse_mem(), when it is freed. + * in use, this function may decide to stop the script engine with an out of + * memory error. * * Returns: %TRUE if the memory could be allocated. %FALSE on OOM. **/ @@ -105,6 +164,7 @@ swfdec_as_context_use_mem (SwfdecAsConte context->memory += bytes; context->memory_since_gc += bytes; + /* FIXME: Don't foget to abort on OOM */ return TRUE; } @@ -184,6 +244,13 @@ swfdec_as_context_collect (SwfdecAsConte SWFDEC_INFO (">> done collecting garbage"); } +/** + * swfdec_as_object_mark: + * @object: a #SwfdecAsObject + * + * Mark @object as being in use. Calling this function is only valid during + * the marking phase of garbage collection. + **/ void swfdec_as_object_mark (SwfdecAsObject *object) { @@ -197,6 +264,13 @@ swfdec_as_object_mark (SwfdecAsObject *o klass->mark (object); } +/** + * swfdec_as_string_mark: + * @string: a garbage-collected string + * + * Mark @string as being in use. Calling this function is only valid during + * the marking phase of garbage collection. + **/ void swfdec_as_string_mark (const char *string) { @@ -205,6 +279,14 @@ swfdec_as_string_mark (const char *strin *str = SWFDEC_AS_GC_MARK; } +/** + * swfdec_as_value_mark: + * @value: a #SwfdecAsValue + * + * Mark @value as being in use. This is just a convenience function that calls + * the right marking function depending on the value's type. Calling this + * function is only valid during the marking phase of garbage collection. + **/ void swfdec_as_value_mark (SwfdecAsValue *value) { @@ -745,27 +827,38 @@ finish: * during evaluation, the return value will be the undefined value. **/ void -swfdec_as_context_eval (SwfdecAsContext *cx, SwfdecAsObject *obj, const char *str, +swfdec_as_context_eval (SwfdecAsContext *context, SwfdecAsObject *obj, const char *str, SwfdecAsValue *val) { - g_return_if_fail (SWFDEC_IS_AS_CONTEXT (cx)); + g_return_if_fail (SWFDEC_IS_AS_CONTEXT (context)); g_return_if_fail (obj == NULL || SWFDEC_IS_AS_OBJECT (obj)); g_return_if_fail (str != NULL); g_return_if_fail (val != NULL); - swfdec_as_context_eval_internal (cx, obj, str, val, FALSE); + swfdec_as_context_eval_internal (context, obj, str, val, FALSE); } +/** + * swfdec_as_context_eval_set: + * @context: a #SwfdecAsContext + * @obj: #SwfdecAsObject to use as source for evaluating or NULL for the + * default object. + * @str: The string to evaluate + * @val: the value to set the variable to + * + * Sets the variable referenced by @str to @val. If @str does not reference + * a valid property, nothing happens. + **/ void -swfdec_as_context_eval_set (SwfdecAsContext *cx, SwfdecAsObject *obj, const char *str, +swfdec_as_context_eval_set (SwfdecAsContext *context, SwfdecAsObject *obj, const char *str, const SwfdecAsValue *val) { - g_return_if_fail (SWFDEC_IS_AS_CONTEXT (cx)); + g_return_if_fail (SWFDEC_IS_AS_CONTEXT (context)); g_return_if_fail (obj == NULL || SWFDEC_IS_AS_OBJECT (obj)); g_return_if_fail (str != NULL); g_return_if_fail (val != NULL); - swfdec_as_context_eval_internal (cx, obj, str, (SwfdecAsValue *) val, TRUE); + swfdec_as_context_eval_internal (context, obj, str, (SwfdecAsValue *) val, TRUE); } /*** AS CODE ***/ diff-tree 677831ce294814177191a5950e5320efb73d6e3d (from f810682741113c7fb94a6a830233ae0d02833c39) Author: Benjamin Otte <otte at gnome.org> Date: Fri Jun 29 02:00:23 2007 +0200 remove unused swfdec_as_context_abort_oom() diff --git a/libswfdec/swfdec_as_context.h b/libswfdec/swfdec_as_context.h index d9815e4..ae625a9 100644 --- a/libswfdec/swfdec_as_context.h +++ b/libswfdec/swfdec_as_context.h @@ -100,7 +100,6 @@ const char * swfdec_as_context_get_strin const char * swfdec_as_context_give_string (SwfdecAsContext * context, char * string); -#define swfdec_as_context_abort_oom(context) swfdec_as_context_abort (context, "Out of memory") void swfdec_as_context_abort (SwfdecAsContext * context, const char * reason); @@ -119,11 +118,11 @@ void swfdec_as_context_return (SwfdecAs void swfdec_as_context_trace (SwfdecAsContext * context, const char * string); -void swfdec_as_context_eval (SwfdecAsContext * cx, +void swfdec_as_context_eval (SwfdecAsContext * context, SwfdecAsObject * obj, const char * str, SwfdecAsValue * val); -void swfdec_as_context_eval_set (SwfdecAsContext * cx, +void swfdec_as_context_eval_set (SwfdecAsContext * context, SwfdecAsObject * obj, const char * str, const SwfdecAsValue * val);
Possibly Parallel Threads
- Branch 'as' - 9 commits - configure.ac libswfdec/swfdec_as_context.c libswfdec/swfdec_as_frame.c libswfdec/swfdec_as_frame.h libswfdec/swfdec_as_function.h libswfdec/swfdec_as_interpret.c libswfdec/swfdec_as_object.c libswfdec/swfdec_as_object.h
- 3 commits - doc/Makefile.am doc/swfdec-docs.sgml doc/swfdec-sections.txt libswfdec/Makefile.am libswfdec/swfdec_as_array.c libswfdec/swfdec_as_boolean.c libswfdec/swfdec_as_context.c libswfdec/swfdec_as_context.h libswfdec/swfdec_as_frame.c
- Branch 'as' - 24 commits - configure.ac doc/Makefile.am doc/swfdec-sections.txt libswfdec/Makefile.am libswfdec/swfdec_amf.c libswfdec/swfdec_as_array.c libswfdec/swfdec_as_context.c libswfdec/swfdec_as_context.h libswfdec/swfdec_as_frame.c
- 8 commits - doc/swfdec-sections.txt libswfdec/swfdec_as_context.c libswfdec/swfdec_as_context.h libswfdec/swfdec_as_interpret.c test/trace
- Branch 'as' - 15 commits - libswfdec/swfdec_as_context.c libswfdec/swfdec_as_context.h libswfdec/swfdec_as_frame.c libswfdec/swfdec_as_frame.h libswfdec/swfdec_as_function.c libswfdec/swfdec_as_function.h libswfdec/swfdec_as_interpret.c