Mercurial > pidgin.yaz
annotate plugins/HOWTO @ 11719:109ee3bfeac5
[gaim-migrate @ 14010]
SF Patch #1333770 from corfe83
"Many times in gaim we use the function
g_slist_remove(list,node->data) to remove an element
from a GSList. If we already have the pointer to the
node we want to delete, it is faster to send it the
pointer to the node to delete rather than the data of
the node (we can do this by calling
g_slist_delete_link(list,node)). This change was made
while looking at glib's documentation and the code in
glib's gslist.c.
This is because as the remove/delete function traverses
each node in the list, it doesn't need to spend an
extra memory access to retrieve the data for each
element in the node it is traversing and then compare,
it can simply compare the pointer. In my tests outside
of gaim, this makes a big difference if the node you
are deleting is at a high index in the list. However,
even if you're deleting the first node, it about breaks
even.
So, I've found each case in gaim where we are calling
g_slist_remove, and we already have the pointer to the
appropriate node to delete (this is often the case when
we're doing a for or while loop on a GSList). I've then
replaced it with the appropriate call to
g_slist_delete_link. I, however, didn't do this in
situations where we are explicitly removing the first
element in the list, because in those situations it is
an unnecessary change.
There should be no difference in behavior, but just in
case I've tried running it with valgrind, which reports
the same number of memory leaks after my patch as
before my patch. Of course, I can't guarantee that my
normal behavior on gaim is hitting all the functions
I've changed, but in general testing it Works For Me (tm)."
As with the last patch, this one may not have a practical performance impact (or maybe it does, I have no idea), but it's not worse for any case. Given two ways of doing things where one is always at least as fast and may be faster under some cases, I like to prefer that faster way. This doesn't make the code any uglier, so I'm applying.
committer: Tailor Script <tailor@pidgin.im>
author | Richard Laager <rlaager@wiktel.com> |
---|---|
date | Sat, 22 Oct 2005 20:48:18 +0000 |
parents | 258c19be6d84 |
children |
rev | line source |
---|---|
7327 | 1 Everything in this file should be considered old and potentially out of |
2 date. For more reliable information, install doxygen and graphiz dot, | |
3 then run | |
4 make docs | |
5 in the gaim source tree. This will produce html docs in gaim/docs/html | |
6 that will provide an api reference and in the related pages section, | |
7 information on perl and c plugins. | |
8 | |
9 | |
93 | 10 Ok, this howto is going to be really short and sweet and to the point. |
11 | |
12 First off, before you do anything else, in all of the files for your plugin, | |
13 put the lines | |
14 | |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
15 #define GAIM_PLUGINS |
93 | 16 #include "gaim.h" |
17 | |
18 I mean this. Without this, all kinds of things will not work correctly. If you | |
19 really want to know exactly what this does, read ../src/gaim.h and learn. But | |
20 if you don't want to do that, just know that it's important. | |
21 | |
22 Now that you've put that there, make sure gaim.h is in your include path. | |
23 | |
24 Ok, now you're ready to write the plugin. | |
25 | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
26 The only function that is required is gaim_plugin_init(GModule *). This gets |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
27 called as soon as it gets loaded (sort of - man dlopen for more details). If |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
28 your function never returns, it will crash gaim! If your plugin uses up all |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
29 the memory in the system, it will crash gaim! Once your plugin gets loaded, |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
30 it effectively becomes a part of gaim, and anything that goes wrong will look |
93 | 31 like it is a problem with gaim itself. I write bugfree code! :) Therefore, it |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
32 is your problem, not mine. (I'm usually nice and willing to help you with your |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
33 problems though.) |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
34 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
35 The GModule* that gets passed to gaim_plugin_init is the handle for the plugin. |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
36 DO NOT CHANGE THIS POINTER! Bad things will happen. You've been warned. It's |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
37 needed for connecting to signals and things. It's a good idea to remember it |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
38 somehow. |
93 | 39 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
40 gaim_plugin_init should return a char*. If the char* returned is not NULL, it |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
41 is interpreted as an error, and used as an error message. See the ChangeLog |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
42 file in this directory for more details. |
391
be408b41c172
[gaim-migrate @ 401]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
144
diff
changeset
|
43 |
93 | 44 You can basically do anything you want in the plugin. You can make function |
45 calls, change public widgets, display new widgets, things like that. But the | |
95
19cffb5bd129
[gaim-migrate @ 105]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
94
diff
changeset
|
46 really neat thing is you can do things at events. For example, when one of |
93 | 47 your buddies signs on, you can instantly send them a message. You can modify |
48 the incoming and outgoing text. You can do all kinds of crazy things. Whatever | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
49 you want. Check out SIGNALS for more information. |
93 | 50 |
51 Plugins can share globals with gaim, but will not share with other plugins. | |
52 This is so if you have a global variable GtkWidget *window in your plugin and | |
53 J. Random Hacker also has the same name on a global variable, you won't be | |
54 constantly overwriting each others' variables. Unfortunately, this also means | |
55 that plugins will have difficulty working together. But then again, that's | |
56 what shared memory is for. | |
57 | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
58 Plugins can be configured. This makes it so they don't have to be recompiled |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
59 in order to change things internal to them, and it's also just a cool feature |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
60 to have :). It's optional; to allow your plugin to be configured, add a |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
61 function called gaim_plugin_config(). The advised course of action is to have |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
62 it pop up a dialog window; but it's your plugin. |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
63 |
93 | 64 When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It |
65 doesn't have to be there, but it's nice if, say, you create a window, and when | |
98
c2d22261e281
[gaim-migrate @ 108]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
95
diff
changeset
|
66 the plugin gets unloaded, it removes the window. Also, all the callbacks you |
c2d22261e281
[gaim-migrate @ 108]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
95
diff
changeset
|
67 have attached to gaim signals will be removed. |
93 | 68 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
69 Plugins can also unload themselves. To do this, call gaim_plugin_unload(GModule *) |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
70 (the GModule* is the handle passed to gaim_plugin_init). When your plugin gets |
445
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
71 unloaded, gaim will remove all of your callbacks. It will not call your |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
72 gaim_plugin_remove function, however, since it will assume you have already |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
73 done the necessary cleanup. |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
74 |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
75 Compilation of the plugins is fairly straight-forward; there is a Makefile in |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
76 this directory that has a rule for making the .so file from a .c file. No |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
77 modification of the Makefile should be necessary, unless if you simply want |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
78 to type 'make' to have it made; otherwise, 'make filename.so' will take |
445
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
79 filename.c and make the .so plugin from it. If you need to link in with extra |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
80 libraries, you can set the environment variable PLUGIN_LIBS to be the libraries |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
81 you want to link with. |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
82 |
93 | 83 There are a few examples in this directory. Enjoy. |