[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
Benjamin Otte
company at kemper.freedesktop.org
Thu Jun 28 17:01:42 PDT 2007
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);
More information about the Swfdec
mailing list