1Clownfish::Docs::WritinUgsCelrasCsoenst(r3i)buted Perl DColcouwmnefnitsaht:i:oDnocs::WritingClasses(3)
2
6 Clownfish::Docs::WritingClasses - Writing Apache Clownfish classes
7
9 Parcels
10 Every Clownfish class belongs to a Clownfish parcel. Parcels are used
11 for namespacing and versioning. Information about parcels is stored in
12 ".cfp" files which contain a JSON hash with the following keys:
13 • name: The parcel’s name. It must contain only letters.
15 • nickname: A short nickname. It must contain only letters. This
17 nickname, followed by an underscore, is used to prefix generated C
18 symbols and macros. Depending on the kind of symbol, a lowercase or
19 uppercase prefix will be used.
20 • version: A version specifier of the following form (without
22 whitespace):
23 version-specifier = "v" version-number
25 version-number = digit+ | digit+ "." version-number
26 • prerequisites: A hash containing the prerequisite parcels. The hash
28 keys are the parcel names. The values contain the minimum required
29 version.
30 An example ".cfp" file might look like:
32 {
34 "name": "Pathfinder",
35 "nickname": "Pfind",
36 "version": "v2.3.8",
37 "prerequisites": {
38 "Clownfish": "v0.6.3"
39 }
40 }
41 A parcel specifier of the following form is used in Clownfish header
43 files:
44 parcel-specifier = "parcel" parcel-name ";"
46 parcel-name = identifier
47 For example:
49 parcel Pathfinder;
51 Every ".cfh" file starts with a parcel specifier containing the name of
53 the parcel for all classes in the header file.
54 Initialization
56 Every Clownfish parcel must be initialized before it is used. The
58 initialization function is named "{parcel_nick}_bootstrap_parcel" and
59 takes no arguments.
60 Example call:
62 pfind_bootstrap_parcel();
64 The generated host language bindings call the bootstrap function
66 automatically. C projects must call the function manually.
67 Short names
69 If a macro with the uppercase name "{PARCEL_NICK}_USE_SHORT_NAMES" is
71 defined before including a generated C header, additional macros
72 without the parcel prefix will be defined for most symbols.
73 Example:
75 #define PFIND_USE_SHORT_NAMES
77 #include <Pathfinder/Graph.h>
78 #include <Pathfinder/Path.h>
79 /* Prefixes can be omitted. */
81 Path *path = Graph_Find_Shortest_Path(graph);
82 /* Without PFIND_USE_SHORT_NAMES, one would have to write: */
84 pfind_Path *path = PFIND_Graph_Find_Shortest_Path(graph);
85 For object types in Clownfish header files, prefixes of class structs
87 can also be omitted unless multiple parcels declare classes with the
88 same last component of the class name.
89 The “Clownfish” parcel
91 The Clownfish runtime classes live in a parcel named "Clownfish" with
93 nickname "Cfish". Consequently, the short name macro is named
94 "CFISH_USE_SHORT_NAMES".
95 Declaring classes
97 Classes are declared in Clownfish header files using a declaration of
98 the following form:
99 class-declaration = class-exposure-specifier?
101 class-modifier*
102 "class" class-name
103 ("nickname" class-nickname)?
104 ("inherits" class-name)?
105 "{" class-contents "}"
106 class-exposure-specifier = "public"
107 class-modifier = "inert" | "final"
108 class-name = identifier | identifier "::" class-name
109 class-nickname = identifier
110 class-contents = (variable-declaration | function-declaration)*
111 Class name components must start with an uppercase letter and must not
113 contain underscores. The last component must contain at least one
114 lowercase letter and must be unique for every class in a parcel.
115 For every class, a type with the name "{parcel_nick}_{Class_Last_Comp}"
117 is defined in the generated C header. This is an opaque typedef used to
118 ensure type safety.
119 For every class, a global variable with the uppercase name
121 "{PARCEL_NICK}_{CLASS_LAST_COMP}" is defined. This variable is a
122 pointer to a Clownfish::Class object which is initialized when
123 bootstrapping the parcel.
124 Non-inert classes inherit from Clownfish::Obj by default.
126 Example of a class declaration:
128 parcel Pathfinder;
130 public class Pathfinder::Graph::VisibilityGraph nickname VisGraph
132 extends Clownfish::Obj {
133 /* Variables and functions */
134 }
135 This will generate:
137 typedef struct pfind_VisibilityGraph pfind_VisibilityGraph;
139 extern cfish_Class *PFIND_VISIBILITYGRAPH;
140 Class exposure
142 API documentation will only be generated for classes with "public"
144 exposure.
145 Inert classes
147 Inert classes must contain only inert variables or inert functions,
149 that is, neither instance variables nor methods. They must not inherit
150 from another class nor be inherited from. They’re essentially nothing
151 more than a namespace for functions and global variables.
152 Final classes
154 For final classes, every method is made final, regardless of the method
156 modifier. Final classes must not be inherited from.
157 Variables
159 Variables are declared with a declaration of the following form:
160 variable-declaration = variable-modifier*
162 type variable-name ";"
163 variable-modifier = "inert"
164 variable-name = identifier
165 Inert variables
167 Inert variables are global class variables of which only a single copy
169 exists. They are declared in the generated C header with the name
170 "{parcel_nick}_{Class_Nick}_{Variable_Name}" and must be defined in a C
171 source file.
172 Example:
174 public class Pathfinder::Path {
176 public inert int max_path_length;
177 }
178 This will generate:
180 extern int pfind_Path_max_path_length;
182 The C source file defining the variable will typically use short names.
184 So the definition will look like:
185 int Path_max_path_length = 5000;
187 Instance variables
189 Non-inert variables are instance variables and added to the class’s
191 ivars struct.
192 Example:
194 public class Pathfinder::Path {
196 int num_nodes;
197 public int
199 Get_Num_Nodes(Path *self);
200 }
201 This will add a "num_nodes" member to the ivars struct of "Path".
203 The ivars struct
205 To access instance variables, the macro
207 "C_{PARCEL_NICK}_{CLASS_LAST_COMP}" must be defined before including
208 the generated header file. This will make a struct named
209 "{parcel_nick}_{Class_Name}IVARS" with a corresponding typedef and
210 short name available that contains all instance variables of the class
211 and all superclasses from the same parcel. Instance variables defined
212 in other parcels are not accessible. This is by design to guarantee ABI
213 stability if the instance variable layout of a superclass from another
214 parcel changes in a different version. If you need to access an
215 instance variable from another parcel, add accessor methods.
216 A pointer to the ivars struct can be obtained by calling an inline
218 function named "{parcel_nick}_{Class_Name}_IVARS". This function takes
219 the object of the class (typically "self") as argument.
220 Example using short names:
222 #define C_PFIND_PATH
224 #define PFIND_USE_SHORT_NAMES
225 #include "Pathfinder/Path.h"
226 int
228 Path_get_num_nodes(Path *self) {
229 PathIVARS *ivars = Path_IVARS(self);
230 return ivars->num_nodes;
231 }
232 Functions
234 function-declaration = function-exposure-specifier?
235 function-modifier*
236 return-type function-name
237 "(" param-list? ")" ";"
238 function-exposure-specifier = "public"
239 function-modifier = "inert" | "inline" | "abstract" | "final"
240 return-type = return-type-qualifier* type
241 return-type-qualifier = "incremented" | "nullable"
242 function-name = identifier
243 param-list = param | param "," param-list
244 param = param-qualifier* type param-name ("=" scalar-constant)?
245 param-name = identifier
246 param-qualifier = "decremented"
247 Function exposure
249 API documentation will only be generated for functions with "public"
251 exposure.
252 Inert functions
254 Inert functions are dispatched statically. They are declared in the
256 generated C header with the name
257 "{parcel_nick}_{Class_Nick}_{Function_Name}" and must be defined in a C
258 source file. They must be neither abstract nor final.
259 Example:
261 public class Pathfinder::Graph::VisibilityGraph nickname VisGraph
263 extends Clownfish::Obj {
264 public inert incremented VisibilityGraph*
266 new(int node_capacity);
267 }
268 This will generate:
270 pfind_VisibilityGraph*
272 pfind_VisGraph_new(int node_capacity);
273 The C source file implementing the inert function will typically use
275 short names. So the implementation will look like:
276 #define PFIND_USE_SHORT_NAMES
278 #include "Pathfinder/Graph/VisibilityGraph.h"
279 VisibilityGraph*
281 VisGraph_new(int node_capacity) {
282 /* Implementation */
283 }
284 Inline functions
286 Inert functions can be inline. They should be defined as static inline
288 functions in a C block in the Clownfish header file. The macro
289 "CFISH_INLINE" expands to the C compiler’s inline keyword and should be
290 used for portability.
291 Methods
293 Non-inert functions are dynamically dispatched methods. Their name must
295 start with an uppercase letter and every underscore must be followed by
296 an uppercase letter. Methods must not be declared inline.
297 The first parameter of a method must be a pointer to an object of the
299 method’s class which receives the object on which the method was
300 invoked. By convention, this parameter is named "self".
301 For every method, an inline wrapper for dynamic dispatch is defined in
303 the generated C header with the name
304 "{PARCEL_NICK}_{Class_Nick}_{Method_Name}". Additionally, an
305 implementing function is declared with the name
306 "{PARCEL_NICK}_{Class_Nick}_{Method_Name}_IMP". The Clownfish compiler
307 also generates a typedef for the method’s function pointer type named
308 "{PARCEL_NICK}_{Class_Nick}_{Method_Name}_t". Wrappers and typedefs are
309 created for all subclasses whether they override a method or not.
310 Example:
312 public class Pathfinder::Graph::VisibilityGraph nickname VisGraph
314 extends Clownfish::Obj {
315 public void
317 Add_Node(VisibilityGraph *self, decremented Node *node);
318 }
319 This will generate:
321 /* Wrapper for dynamic dispatch */
323 static inline void
324 PFIND_VisGraph_Add_Node(pfind_VisibilityGraph *self, pfind_Node *node) {
325 /* Inline code for wrapper */
326 }
327 /* Declaration of implementing function */
329 void
330 PFIND_VisGraph_Add_Node_IMP(pfind_VisibilityGraph *self,
331 pfind_Node *node);
332 /* Declaration of function pointer type */
334 typedef void
335 (*PFIND_VisGraph_Add_Node_t)(pfind_VisibilityGraph *self,
336 pfind_Node *node);
337 The implementing function of non-abstract methods must be defined in a
339 C source file. This file will typically define the short names macro.
340 So the implementation will look like:
341 #define PFIND_USE_SHORT_NAMES
343 #include "Pathfinder/Graph/VisibilityGraph.h"
344 void
346 VisGraph_Add_Node_IMP(VisibilityGraph *self, Node *node) {
347 /* Implementation */
348 }
349 Looking up methods
351 Clownfish defines a macro named "CFISH_METHOD_PTR" that looks up the
353 pointer to the implementing function of a method. The first parameter
354 of the macro is a pointer to the Clownfish::Class object of the
355 method’s class, the second is the unshortened name of the method
356 wrapper. If short names for the Clownfish parcel are used, the macro is
357 also available under the name "METHOD_PTR".
358 To lookup methods from a superclass, there’s a macro
360 "CFISH_SUPER_METHOD_PTR" with the same parameters.
361 Example using short names:
363 // Note that the name of the method wrapper must not be shortened.
365 VisGraph_Add_Node_t add_node
366 = METHOD_PTR(VISIBILITYGRAPH, Pfind_VisGraph_Add_Node);
367 VisGraph_Add_Node_t super_add_node
369 = SUPER_METHOD_PTR(VISIBILITYGRAPH, Pfind_VisGraph_Add_Node);
370 Abstract methods
372 For abstract methods, the Clownfish compiler generates an implementing
374 function which throws an error. They should be overridden in a
375 subclass.
376 Final methods
378 Final methods must not be overridden. They must not be abstract.
380 Nullable return type
382 If a function has a nullable return type, it must return a pointer.
384 Non-nullable functions must never return the NULL pointer.
385 Incremented return type
387 Incremented return types must be pointers to Clownfish objects. The
389 function will either return a new object with an initial reference
390 count of 1 or increment the reference count. The caller must decrement
391 the reference count of the returned object when it’s no longer used.
392 For returned objects with non-incremented return type, usually no
394 additional handling of reference counts is required. Only if an object
395 is returned from an accessor or a container object and the caller wants
396 to use the object longer than the returning object retains a reference,
397 it must increment the reference count itself and decrement when the
398 object is no longer used.
399 Decremented parameters
401 Decremented parameters must be pointers to Clownfish objects. The
403 function will either decrement the reference count of the passed-in
404 object or retain a reference without incrementing the reference count.
405 If the caller wants to use the passed-in object afterwards, it usually
406 must increment its reference count before the call and decrement it
407 when it’s no longer used. If the caller does not make further use of
408 the passed-in object, it must not decrement its reference count after
409 the call.
410 This is typically used in container classes like Vector:
412 String *string = String_newf("Hello");
414 Vec_Push(array, (Obj*)string);
415 // No need to DECREF the string.
416 Default parameter values
418 Default parameter values can be given as integer, float, or string
420 literals. The values "true", "false", and "NULL" are also supported.
421 The default values are only used by certain host language bindings.
422 They’re not supported when calling a function from C.
423 C blocks
425 Clownfish headers can contain C blocks which start with a line
426 containing the string "__C__" and end on a line containing the string
427 "__END_C__". The contents of a C block are copied verbatim to the
428 generated C header.
429 Example:
431 __C__
433 struct pfind_AuxiliaryStruct {
435 int a;
436 int b;
437 };
438 __END_C__
440 Object life cycle
442 Object creation
443 Objects are allocated by invoking the "Make_Obj" method on a class’s
445 Clownfish::Class object.
446 Any inert function can be used to construct objects from C. But to
448 support inheritance and object creation from the host language,
449 Clownfish classes need a separate function to initialize objects. The
450 initializer must take a pointer to an object as first argument and
451 return a pointer to the same object. If the parent class has an
452 initializer, it should be called first by the subclass’s initializer.
453 By convention, the standard constructor is named "new" and the standard
455 initializer "init".
456 Example:
458 /* Clownfish header */
460 class Vehicle {
462 double max_speed;
463 inert Vehicle*
465 init(Vehicle *self, double max_speed);
466 }
467 class Train inherits Vehicle {
469 double track_gauge;
470 inert incremented Train*
472 new(double max_speed, double track_gauge);
473 inert Train*
475 init(Train *self, double max_speed, double track_gauge);
476 }
477 /* Implementation */
479 Train*
481 Train_new(double max_speed, double track_gauge) {
482 Train *self = (Train*)Class_Make_Obj(TRAIN);
483 return Train_init(self, max_speed, track_gauge);
484 }
485 Train*
487 Train_init(Train *self, double max_speed, double track_gauge) {
488 Vehicle_init((Vehicle*)self, max_speed);
489 self->track_gauge = track_gauge;
490 return self;
491 }
492 Reference counting
494 Clownfish uses reference counting for memory management. Objects are
496 created with a reference count of 1. There are two macros
497 "CFISH_INCREF" and "CFISH_DECREF" to increment and decrement reference
498 counts. If short names for the Clownfish parcel are enabled, the macros
499 can be abbreviated to "INCREF" and "DECREF". Both macros take a pointer
500 to an object as argument. NULL pointers are allowed. "CFISH_INCREF"
501 returns a pointer to the object. This value might differ from the
502 passed-in pointer in some cases. So if a reference is retained, the
503 pointer returned from "CFISH_INCREF" should be used. "CFISH_DECREF"
504 returns the modified reference count.
505 Examples:
507 self->value = INCREF(arg);
509 DECREF(object);
511 Object destruction
513 If an object’s reference count reaches 0, its "Destroy" method is
515 called. This public method takes no arguments besides "self" and has
516 no return value. It should release the resources held by the object
517 and finally call the "Destroy" method of the superclass via the
518 "CFISH_SUPER_DESTROY" macro with short name "SUPER_DESTROY". This macro
519 takes the "self" pointer as first argument and a pointer to the
520 object’s Clownfish::Class as second argument. The "Destroy" method of
521 the Clownfish::Obj class will eventually free the object struct.
522 Example:
524 /* Clownfish header */
526 class Path {
528 Vector *nodes;
529 public void
531 Destroy(Path *self);
532 }
533 /* Implementation */
535 void
537 Path_Destroy_IMP(Path *self) {
538 DECREF(self->nodes);
539 SUPER_DESTROY(self, PATH);
540 }
541 Documentation
543 The Clownfish compiler creates documentation in the host language’s
544 preferred format from so-called DocuComments found in the ".cfh" files.
545 DocuComments use Markdown (CommonMark <http://commonmark.org/> flavor)
546 for formatting. DocuComments are multi-line C-style comments that
547 start with "/**". They immediately precede the documented class, inert
548 function, or method. A left border consisting of whitespace and
549 asterisks is stripped.
550 The DocuComment for a class should start with a short description
552 (everything up until the first period ".") which may appear in the name
553 section of a man page, for example.
554 DocuComments for functions and methods may end with a series of @param
556 and @return directives which document the parameters and return values.
557 Example:
559 /** Class describing a train.
561 *
562 * The Train class describes a train. It extends the Vehicle class and
563 * adds some useful properties specific to trains.
564 */
565 public class Train inherits Vehicle {
566 /** Create a new Train object.
567 *
568 * @param max_speed The maximum speed in km/h.
569 * @param track_gauge The track gauge in mm.
570 */
571 public inert incremented Train*
572 new(double max_speed, double track_gauge);
573 /** Accessor for maximum speed.
575 *
576 * @return the maximum speed in km/h.
577 */
578 public double
579 Get_Max_Speed(Train *self);
580 }
581 The Clownfish compiler also looks for standalone Markdown ".md" files
583 in the source directories which will be included in the documentation.
584perl v5.36.0 2023-01-20Clownfish::Docs::WritingClasses(3)