summaryrefslogtreecommitdiffstats
path: root/under_review/code-generation.md
blob: 5c25a13f0f44b4dbfd461a05e4fade1b94d1b653 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
Goal
----

Reduce internal duplication of code by generating from templates.

Summary
-------

The translator calling convention is based on long lists of
operation-specific arguments instead of a common "control block"
struct/union. As a result, many parts of our code are highly repetitive
both internally and with respect to one another. As an example of
internal redundancy, consider how many of the functions in
[defaults.c](https://github.com/gluster/glusterfs/blob/master/libglusterfs/src/defaults.c)
look similar. As an example of external redundancy, consider how the
[patch to add GF\_FOP\_IPC](http://review.gluster.org/#/c/8812/) has to
make parallel changes to 17 files - defaults, stubs, syncops, RPC,
io-threads, and so on. All of this duplication slows development of new
features, and creates huge potential for errors as definitions that need
to match don't. Indeed, during development of a code generator for NSR,
several such inconsistencies have already been found.

Owners
------

Jeff Darcy <jdarcy@redhat.com>

Current status
--------------

Proposed, awaiting approval.

Related Feature Requests and Bugs
---------------------------------

Code generation was already used successfully in the first generation of
[NSR](../GlusterFS 3.6/New Style Replication.md) and will continue to be
used in the second.

Detailed Description
--------------------

See Summary section above.

Benefit to GlusterFS
--------------------

-   Fewer bugs from inconsistencies between how similar operations are
    handled within one translator, or how a single operation is handled
    across many.

-   Greater ease of adding new operation types, or new translators which
    implement similar functionality for many operations.

Scope
-----

### Nature of proposed change

The code-generation infrastructure itself consists of three parts:

-   A list of operations and their associated arguments (both original
    and callback, with types).

-   A script to combine this list with a template to do the actual
    generation.

-   Modifications to makefiles etc. to do generation during a build.

The first and easiest target is auto-generated default functions. Stubs
and syncops could follow pretty quickly. Other possibilities include:

-   GFAPI (both C and Python)

-   glupy

-   RPC (replace rpcgen?)

-   io-threads

-   changelog (the [full-data-logging
    translator](https://forge.gluster.org/~jdarcy/glusterfs-core/jdarcys-glusterfs-data-logging)
    on the forge already uses this technique)

Even something as complicated as AFR/NSR/EC could use code generation to
handle quorum checks more consistently, wrap operations in transactions,
and so on. NSR already does; the others could.

### Implications on manageability

None.

### Implications on presentation layer

None.

### Implications on persistence layer

None.

### Implications on 'GlusterFS' backend

None.

### Modification to GlusterFS metadata

None.

### Implications on 'glusterd'

None.

How To Test
-----------

This change is not intended to introduce any change visible except to
developers. Standard regression tests should be sufficient to verify
that no such change has occurred.

User Experience
---------------

None.

Dependencies
------------

None.

Documentation
-------------

Developer documentation should explain the format of the fop-description
and template files. In particular developers need to know what variables
are available for use in templates, and how to add new ones.

Status
------

Patch available to generate default functions. Others to follow.

Comments and Discussion
-----------------------