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 > 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