1Clownfish::Docs::ClassIUnsterro(C3opnmt)ributed Perl DocCulmoewnntfaitsiho:n:Docs::ClassIntro(3pm)
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 “short name macro” 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 don’t 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 “nickname” – 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 “inert” function of a class that returns a new
49       object. In Clownfish parlance, an inert function is any function in a
50       class that isn’t 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 “incremented” object. If you’re 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 won’t be destroyed too
78       early:
79
80           obj = INCREF(obj);
81
82       This invocation of INCREF must be matched by a DECREF when you’re done
83       with the object.
84
85       Some methods, for example in container classes, take “decremented”
86       objects as arguments. From the caller’s 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.38.0                      2023-07-20  Clownfish::Docs::ClassIntro(3pm)