1Clownfish::Docs::ClassIUnsterro(C3o)ntributed Perl DocumCelnotwantfiiosnh::Docs::ClassIntro(3)
2
3
4

NAME

6       Clownfish::Docs::ClassIntro - Working with Apache Clownfish classes in
7       C
8

DESCRIPTION

10   Inititalizing Clownfish parcels
11       Every Clownfish parcel must be initialized before it is used. The
12       initialization function is named "{parcel_nick}_bootstrap_parcel" and
13       takes no arguments.
14
15       Example:
16
17           cfish_bootstrap_parcel();
18
19   Including the generated header file
20       To use Clownfish classes from C code, the header file generated by the
21       Clownfish compiler must be included. The name of the C header is
22       derived from the name of the Clownfish ".cfh" header. It can also be
23       found in the class documentation.
24
25       Typically, the Xshort name macroX should be defined before including a
26       Clownfish header. Its name is derived from the parcel nickname and has
27       the form "{PARCEL_NICK}_USE_SHORT_NAMES". If the short name macro is in
28       effect, you donXt have to worry about parcel prefixes.
29
30       Example:
31
32           #define CFISH_USE_SHORT_NAMES
33
34           #include <Clownfish/String.h>
35           #include <Clownfish/Vector.h>
36
37   Function and method prefixes
38       Clownfish classes can have a XnicknameX X a shorter version of the
39       class name that is used for function and method prefixes. The nickname
40       can be found in the class documentation.
41
42       For example the String class has the nickname "Str".
43
44   Creating objects
45       A Clownfish object is an opaque struct referenced by pointer.
46
47       Most classes come with one or more constructors. On the C level, a
48       constructor is simply an XinertX function of a class that returns a new
49       object. In Clownfish parlance, an inert function is any function in a
50       class that isnXt a method, similar to static methods in Java or static
51       member functions in C++.
52
53       Example:
54
55           // Notice the use of nickname "Str" in the constructor prefix.
56           String *name = Str_newf("%s %s", first, last);
57
58   Calling methods
59       Calling methods is straightforward. The invocant is always passed as
60       first argument.
61
62           // Notice the use of nickname "Str" in the method prefix.
63           size_t len = Str_Length(name);
64
65       Method names always start with an uppercase letter.
66
67   Memory management
68       Clownfish uses reference counting to manage memory. Constructors, but
69       also some methods, return an XincrementedX object. If youXre done with
70       an incremented object, you must decrease its reference count to avoid
71       leaking memory. Use the "DECREF" macro to release an object:
72
73           DECREF(name);
74
75       Some other methods return non-incremented objects. If you want to
76       retain a reference to such an object, you must increase its reference
77       count using the "INCREF" macro to make sure it wonXt be destroyed too
78       early:
79
80           obj = INCREF(obj);
81
82       This invocation of INCREF must be matched by a DECREF when youXre done
83       with the object.
84
85       Some methods, for example in container classes, take XdecrementedX
86       objects as arguments. From the callerXs perspective, passing a
87       decremented argument is equivalent to passing a non-decremented
88       argument and calling DECREF afterwards. Typically, this avoids a call
89       to DECREF in the calling code. But sometimes, it must be compensated
90       with an INCREF.
91
92   Further reading
93       •   Building Clownfish projects in C environments
94
95       •   Writing Clownfish classes
96
97
98
99perl v5.36.0                      2022-07-22    Clownfish::Docs::ClassIntro(3)