You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucy.apache.org by nw...@apache.org on 2014/08/22 20:27:05 UTC
git commit: Update Clownfish documentation
Repository: lucy-clownfish
Updated Branches:
refs/heads/documentation [created] c66300d41
Update Clownfish documentation
* Parcel prerequisites.
* Single parcel specifier per header file.
* ivars struct.
* Parcel prefix of methods.
* Details of class, function and variable exposure are yet to be
decided.
* Misc clarifications.
Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/c66300d4
Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/c66300d4
Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/c66300d4
Branch: refs/heads/documentation
Commit: c66300d41772278a29a24b739c8b87ef34091205
Parents: e6cf065
Author: Nick Wellnhofer <we...@aevum.de>
Authored: Fri Aug 22 20:19:13 2014 +0200
Committer: Nick Wellnhofer <we...@aevum.de>
Committed: Fri Aug 22 20:24:02 2014 +0200
----------------------------------------------------------------------
runtime/perl/lib/Clownfish.pod | 114 +++++++++++++++++++++++-------------
1 file changed, 72 insertions(+), 42 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/c66300d4/runtime/perl/lib/Clownfish.pod
----------------------------------------------------------------------
diff --git a/runtime/perl/lib/Clownfish.pod b/runtime/perl/lib/Clownfish.pod
index a4dcbb5..e177adc 100644
--- a/runtime/perl/lib/Clownfish.pod
+++ b/runtime/perl/lib/Clownfish.pod
@@ -15,7 +15,7 @@
=head1 NAME
-Clownfish - Symbiotic object system.
+Clownfish - Apache Clownfish symbiotic object system.
=head1 VERSION
@@ -23,8 +23,8 @@ Clownfish - Symbiotic object system.
=head1 DESCRIPTION
-Clownfish is a "symbiotic" object system for C which is designed to pair
-with a "host" dynamic language environment, facilitating the development
+Apache Clownfish is a "symbiotic" object system for C which is designed to
+pair with a "host" dynamic language environment, facilitating the development
of high performance host language extensions. Clownfish classes are
declared in header files with a C<.cfh> extension. The Clownfish headers
are used by the Clownfish compiler to generate C header files and host
@@ -63,6 +63,11 @@ arrays and hash tables.
=item *
+Guaranteed ABI stability when adding or reordering methods or instance
+variables.
+
+=item *
+
Modularity.
=item *
@@ -83,11 +88,6 @@ Documentation generator.
Support for more host languages.
-=item *
-
-Guaranteed ABI stability when adding or reordering methods or instance
-variables.
-
=back
=head1 USING CLOWNFISH CLASSES
@@ -121,6 +121,11 @@ A version specifier of the following form (without whitespace):
version-specifier = "v" version-number
version-number = digit | digit "." version-number
+=item prerequisites
+
+A hash containing the prerequisite parcels. The hash keys are the parcel
+names. The values contain the minimum required version.
+
=back
An example C<.cfp> file might look like:
@@ -128,7 +133,10 @@ An example C<.cfp> file might look like:
{
"name": "Pathfinder",
"nickname": "Pfind",
- "version": "v2.3.8"
+ "version": "v2.3.8",
+ "prerequisites": {
+ "Clownfish": "v0.4.0"
+ }
}
A parcel specifier of the following form is used in Clownfish header files:
@@ -140,7 +148,8 @@ For example:
parcel Pathfinder;
-All classes following a parcel specifier will be associated with that parcel.
+Every C<.cfh> file starts with a parcel specifier containing the name of
+the parcel for all classes in the header file.
=head3 Initialization
@@ -152,6 +161,9 @@ Example call:
pfind_bootstrap_parcel();
+The generated host language bindings call the bootstrap function
+automatically. C projects must call the function manually.
+
=head3 Short names
If a macro with the uppercase name C<{PARCEL_NICK}_USE_SHORT_NAMES> is
@@ -168,7 +180,7 @@ Example:
Path *path = Graph_Find_Shortest_Path(graph);
/* Without PFIND_USE_SHORT_NAMES, one would have to write: */
- pfind_Path *path = Pfind_Graph_Find_Shortest_Path(graph);
+ pfind_Path *path = PFIND_Graph_Find_Shortest_Path(graph);
For object types in Clownfish header files, prefixes of class structs can
also be omitted unless multiple parcels declare classes with the same last
@@ -201,16 +213,16 @@ Class name components must start with an uppercase letter and must not contain
underscores. The last component must contain at least one lowercase letter and
must be unique for every class in a parcel.
-For every class, a struct with the name C<{parcel_nick}_{Class_Last_Comp}>
-and a corresponding typedef are declared in the generated C header. The struct
-members are only visible if the uppercase macro
-C<C_{PARCEL_NICK}_{CLASS_LAST_COMP}> is defined before including the header
-file.
+For every class, a type with the name C<{parcel_nick}_{Class_Last_Comp}>
+is defined in the generated C header. This is an opaque typedef used to
+ensure type safety.
For every class, a global variable with the uppercase name
C<{PARCEL_NICK}_{CLASS_LAST_COMP}> is defined. This variable is a pointer to
a Clownfish::Class object which is initialized when bootstrapping the parcel.
+Non-inert classes inherit from Clownfish::Obj by default.
+
Example of a class declaration:
parcel Pathfinder;
@@ -222,23 +234,19 @@ Example of a class declaration:
This will generate:
- struct pfind_VisibilityGraph {
- /* Instance variables */
- };
typedef struct pfind_VisibilityGraph pfind_VisibilityGraph;
extern cfish_Class *PFIND_VISIBILITYGRAPH;
=head3 Class exposure
-Classes without public exposure have parcel exposure. They are not visible
-outside of the parcel and must not contain public variables or functions.
+TODO
=head3 Inert classes
-Inert classes must contain only inert variables or inert methods, that is,
+Inert classes must contain only inert variables or inert functions, that is,
neither instance variables nor methods. They must not inherit from another
-class or be inherited from. Non-inert classes inherit from Clownfish::Obj by
-default.
+class or be inherited from. They're essentially nothing more than a
+namespace for functions and global variables.
=head3 Final classes
@@ -258,8 +266,8 @@ Variables are declared with a declaration of the following form:
=head3 Inert variables
-Inert variables are class variables of which only a single copy exists.
-They are declared in the generated C header with the name
+Inert variables are global class variables of which only a single copy
+exists. They are declared in the generated C header with the name
C<{parcel_nick}_{Class_Nick}_{Variable_Name}> and must be defined in a C
source file.
@@ -280,13 +288,12 @@ definition will look like:
=head3 Inert variable exposure
-Inert variables without public exposure have parcel exposure. They are not
-visible outside of the parcel.
+TODO
=head3 Instance variables
-Non-inert variables are instance variables and added to the class struct. They
-must not have an exposure specifier.
+Non-inert variables are instance variables and added to the class's ivars
+struct. They must not have an exposure specifier.
Example:
@@ -297,9 +304,26 @@ Example:
Get_Num_Nodes(Path *self);
}
-This will add a C<num_nodes> member to struct C<pfind_Path>. To access the
-member, the macro C<C_PFIND_PATH> must be defined before including the
-generated header file:
+This will add a C<num_nodes> member to the ivars struct of C<Path>.
+
+=head3 The ivars struct
+
+To access instance variables, the macro C<C_{PARCEL_NICK}_{CLASS_LAST_COMP}>
+must be defined before including the generated header file. This will make
+a struct named C<{parcel_nick}_{Class_Name}IVARS> with a corresponding
+typedef and short name available that contains all instance variables
+of the class and all superclasses from the same parcel. Instance
+variables defined in other parcels are not accessible. This is by
+design to guarantee ABI stability if the instance variable layout
+of a superclass from another parcel changes in a different version.
+If you need to access an instance variable from another parcel,
+add accessor methods.
+
+A pointer to the ivars struct can be obtained by calling an inline
+function named C<{parcel_nick}_{Class_Name}_IVARS>. This function
+takes the object of the class (typically C<self>) as argument.
+
+Example using short names:
#define C_PFIND_PATH
#define PFIND_USE_SHORT_NAMES
@@ -307,7 +331,8 @@ generated header file:
int
Path_get_num_nodes(Path *self) {
- return self->num_nodes;
+ PathIVARS *ivars = Path_IVARS(self);
+ return ivars->num_nodes;
}
=head2 Functions
@@ -328,8 +353,7 @@ generated header file:
=head3 Function exposure
-Functions without public exposure have parcel exposure. They are not
-visible outside of the parcel.
+TODO
=head3 Inert functions
@@ -381,11 +405,11 @@ this parameter is named C<self>.
For every method, an inline wrapper for dynamic dispatch is defined in
the generated C header with the name
-C<{Parcel_Nick}_{Class_Nick}_{Method_Name}>. Additionally, an
+C<{PARCEL_NICK}_{Class_Nick}_{Method_Name}>. Additionally, an
implementing function is declared with the name
-C<{Parcel_Nick}_{Class_Nick}_{Method_Name}_IMP>. The Clownfish compiler also
+C<{PARCEL_NICK}_{Class_Nick}_{Method_Name}_IMP>. The Clownfish compiler also
generates a typedef for the method's function pointer type named
-C<{Parcel_Nick}_{Class_Nick}_{Method_Name}_t>. Wrappers and typedefs are
+C<{PARCEL_NICK}_{Class_Nick}_{Method_Name}_t>. Wrappers and typedefs are
created for all subclasses whether they override a method or not.
Example:
@@ -401,18 +425,18 @@ This will generate:
/* Wrapper for dynamic dispatch */
static inline void
- Pfind_VisGraph_Add_Node(pfind_VisibilityGraph *self, pfind_Node *node) {
+ PFIND_VisGraph_Add_Node(pfind_VisibilityGraph *self, pfind_Node *node) {
/* Inline code for wrapper */
}
/* Declaration of implementing function */
void
- Pfind_VisGraph_Add_Node_IMP(pfind_VisibilityGraph *self,
+ PFIND_VisGraph_Add_Node_IMP(pfind_VisibilityGraph *self,
pfind_Node *node);
/* Declaration of function pointer type */
typedef void
- (*Pfind_VisGraph_Add_Node_t)(pfind_VisibilityGraph *self,
+ (*PFIND_VisGraph_Add_Node_t)(pfind_VisibilityGraph *self,
pfind_Node *node);
The implementing function of non-abstract methods must be defined in a C source
@@ -483,6 +507,12 @@ before the call and decrement it when it's no longer used. If the caller does
not make further use of the passed-in object, it must not decrement its
reference count after the call.
+This is typically used in container classes like VArray:
+
+ String *string = String_newf("Hello");
+ VA_Push(array, (Obj*)string);
+ // No need to DECREF the string.
+
=head3 Default parameter values
Default parameter values can be given as integer, float, or string literals.