File: HACKING

package info (click to toggle)
gnet 2.0.8-1
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 4,148 kB
  • ctags: 2,281
  • sloc: ansic: 15,309; sh: 8,845; xml: 6,789; makefile: 527; perl: 454
file content (180 lines) | stat: -rw-r--r-- 5,603 bytes parent folder | download | duplicates (3)
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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

GNet HACKING
------------

Information for potential GNet hackers


What to do (in general)
-----------------------

We will always accept bug and portability fixes.  If you are
interested in doing something more major, please write
gnet-dev@gnetlibrary.net first.  This is so we know what people are
doing and can offer advice.  Also see the TODO file for ideas on the
direction we want to take GNet.  We _strongly_ recommend, if you are
contributing a feature, that you fully implement and test the feature
in your own program before submitting a patch.  This ensures that the
feature is tested the interface is reasonably mature.


Mailing list
------------

gnet-dev@gnetlibrary.org is the development mailing list.  See the
README for information on how to subscribe.


How to check out GNet anonymously
---------------------------------

  > cd <directory I want GNet to go in>
  > setenv CVSROOT :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome
  > cvs login	[there is no password, hit return if it asks]
  > cvs -z3 checkout gnet

Be warned that the repository version of GNet may be instable or may
not even compile.


Building GNet from CVS
----------------------

AUTOCONF 1.6 IS RECOMMENDED.  It's the future, whether we like it or
not.

Run autogen.sh in the gnet directory to build GNet.  This script
requires aclocal, autoheader, libtoolize, automake, and autoconf.

If aclocal isn't finding certain macros, use the environment variable
ACLOCAL_FLAGS to included the needed directory.  For example, if it's
not picking up macros in /usr/local/share/aclocal, set ACLOCAL_FLAGS
to "-I /usr/local/share/aclocal".  Multiple include directories can be
used.

MIGRATING TO AUTOCONF 1.6 HINT.  Create a macros directory and put the
old glib.m4, libtool.m4, and pkg.m4 in it (from where ever those were
before).


How to make code contributions
------------------------------

We only accept code contributions in the form of a unified diff
against the latest released version and, preferably, the version in
CVS.  If you have added to the API, you _must_ provide complete gtkdoc
style comments in the source.  When appropriate, you should also
submit a test/example program.
            
To make a unified diff, please follow these instructions:
   
1. Remove temporary files:
    make distclean

2. Rename your source tree:
    cd ..
    mv gnet-0.1.4 gnet-0.1.4-snazzy-feature

3. Unpack the original gnet library source alongside it:
    tar zxf /tmp/gnet-0.1.4.tar.gz

4. Generate the diffs:
   diff -urNb gnet-0.1.4 gnet-0.1.4-snazzy-feature > /tmp/gnet.patch

5. Check the patch and remove any unnecessary patches from the file.

6. If you've added several features, it's best to send them as
   several independent patches if you can.

7. Don't forget to add your name and email address to AUTHORS so that
   you assert copyright over GNet and help to keep GNet free!


If you have just patched one or two files, then making patches is even
easier. For each file, just do:

  cp file.c file.c.orig
   [Make changes to file.c ...]
  diff -u file.c.orig file.c > /tmp/file.c.patch

and just send us the patch: /tmp/file.c.patch.


Testing GNet
------------

Before submitting a patch, run the regression tests and make sure they
pass.  It's easy:

  > cd tests
  > make check
  [tests will compile and you will see something like this:]
  PASS: hash
  PASS: pack
  PASS: unpack
  PASS: inetaddr_test
  PASS: uri_test
  PASS: ipv6_test
  ==================
  All 6 tests passed
  ==================

The above tests do not use the network.  There are some tests that do
use the network.  To enable them, either run autogen.sh or pass
--enable-network-tests=yes to configure.

Please write automated tests for new modules when appropriate.  Place
the test in the tests directory and add it to the Makefile.am.  Test
programs should exit(0) if successful and exit(1) otherwise.  Tests
that use the network should



Fork vs. Pthread in asynchronous DNS lookup
-------------------------------------------

Running a simple benchmark on a Dual Pentium II running Linux 2.4.4,
shows that pthreads outperforms forking slightly.  The benchmark
performs an asynchronous lookup of www.microsoft.com asynchronously
100 times in sequence.  Results below.

time ./dnstest www.microsoft.com async 100 > /dev/null

Pthread
4.850u 0.490s 0:05.07 105.3%	0+0k 0+0io 1179pf+0w
4.840u 0.540s 0:05.08 105.9%	0+0k 0+0io 1179pf+0w
4.820u 0.420s 0:05.04 103.9%	0+0k 0+0io 1179pf+0w

Fork
5.090u 0.810s 0:03.52 167.6%	0+0k 0+0io 6013pf+0w
4.750u 0.840s 0:03.24 172.5%	0+0k 0+0io 5492pf+0w
4.690u 0.890s 0:03.38 165.0%	0+0k 0+0io 5492pf+0w

Pthread
4.810u 0.680s 0:05.30 103.5%	0+0k 0+0io 1700pf+0w
4.830u 0.550s 0:05.07 106.1%	0+0k 0+0io 1179pf+0w
4.880u 0.400s 0:05.03 104.9%	0+0k 0+0io 1179pf+0w

Fork
5.050u 0.890s 0:03.50 169.7%	0+0k 0+0io 6013pf+0w
4.850u 0.910s 0:03.24 177.7%	0+0k 0+0io 5492pf+0w
5.160u 0.680s 0:03.30 176.9%	0+0k 0+0io 5492pf+0w


In a different benchmark, where './dnstest www.microsoft.com async 1'
is run 100 times, fork outperforms pthreads.  I would hypothesize that
the pthread library has an expensive initialization step.

time ./dnsbench > /dev/null

Fork
6.810u 6.080s 0:17.05 75.6%	0+0k 0+0io 113543pf+0w
6.120u 6.740s 0:17.11 75.1%	0+0k 0+0io 113543pf+0w
6.530u 6.490s 0:17.08 76.2%	0+0k 0+0io 113543pf+0w
6.180u 6.440s 0:17.09 73.8%	0+0k 0+0io 113543pf+0w

Pthread
11.510u 6.920s 0:17.32 106.4%	0+0k 0+0io 118564pf+0w
11.370u 6.500s 0:17.10 104.5%	0+0k 0+0io 118043pf+0w
10.850u 7.290s 0:16.95 107.0%	0+0k 0+0io 118043pf+0w
10.810u 7.010s 0:17.08 104.3%	0+0k 0+0io 118043pf+0w