# HG changeset patch # User Matti Hamalainen # Date 1222103652 -10800 # Node ID dde7262d0a352f8ac799d7680d974ec0e7b88be6 # Parent 1f03f17e263e7bfc35d568b747170a7014786cbf Moved HACKING and TODO under doc/. diff -r 1f03f17e263e -r dde7262d0a35 HACKING --- a/HACKING Mon Sep 22 06:46:46 2008 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,123 +0,0 @@ -Hacking / coding guide for Audacious and Audacious-plugins -========================================================== -(C) Copyright 2008 Audacious Development Team - - -Preamble -======== - -This document describes the guidelines for people who wish to work on -improving or cleaning up Audacious media player, or any of the plugins -we distribute in the plugins package. - -It is probably obvious to anyone who has taken a look into the depths -of Audacious source, that many of these guidelines are not actually -followed currently in all places, if at all. - -In fact, the purpose of this document is to act as a target to aim at, -when noticing and cleaning up uncompliant code.. or writing new code. - - -Coding guidelines -================= -- Public functions in Audacious core SHOULD be documented via Doxygen - comments! In this case "public" means any functions that span modules - OR are available to plugins. - - Of course, most functions currently lack documentation. If you have - spare time, improve the situation. - - -- We use Glib for portability. This means that we have sized integer types - such as gint{16,32,64}, etc. and shorthand types like guint and guchar - provided, so please do use them. - - Arguably C99 provides inttypes.h with similar types, but C99 support - may not be complete on all platforms, it is both safer and more uniform - to use glib types. - - -- Use other glib functionality, especially string handling like: - * g_snprintf(), g_strdup_printf(), g_strdup() ... - - -- However, avoid following Glib things: - * GString - Useless in most cases compared to normal 'C' string functions - and introduces conversions back and forth. - - * GList - GList is slow, either use GQueue or libmowgli lists. - - -- Be sure to know when you are handling UTF-8 or something else! Glib offers - special g_ascii_*() functions for certain operations that you might need - when handling non-unicode strings. - - -- When reading data from files, it's usually a BIG mistake to read structs - directly from the stream! This is not portable, as C does not guarantee - a struct not to have alignment padding (unless the struct is "packed", - but see below.) In effect sizeof(struct), unless packed, on some platform - may not be equal to some other platform. - - Making struct "packed" via the C packed qualifier or "#pragma pack()" is - a solution, but this must be used with care. Unaligned memory access - causes performance penalties, and may cause other, more serious problems - in some cases. For example, code written in assembler may not know about - the un-alignment, and may thus fail with 'bus errors' on platforms that - strictly required aligned data. - - The 100% safe way is to read individual members of the struct one by one - from the stream. This may be bothersome, but by doing so, your code - will be portable for sure. - - -- Always use Glib sized types for reading integer data from file streams. - Using plain C types (like 'long int' for example) is not wise, because - they may be of different size on different platforms depending on the - platform ABI. For example, on some 64-bit platforms, 'long int' is - 64 bits, while on 32-bit platforms it is 32 bits. - - -- Audacious core provides some helper functions for reading endian-dependant - integers from VFS streams (aud_vfs_fget_{le,be}{16,32,64}), see vfs.h and - documentation for more information. - - -- Avoid reinventing wheels, avoid code duplication. If same thing is done - in two places, it should be in a library, or possibly in Audacious core. - Discuss about it with fellow developers. - - -- In the core, DO NOT WRITE CODE THAT IS DEPENDENT ON A SPECIFIC UI OR - INTERFACE. The core should NEVER care what interface is in use. - - -Additional style guidelines -=========================== - -- Indentation: Use the same indentation style (also spaces vs. tabs) - as the file you are editing. In new files/code, use indentation of - 4 spaces (no tabs). When moving functions to new files, PLEASE - reindent the code. - -- Whitespace usage in code: - - a = 1; - - if (b == d && !strcmp(a, c)) ... - -- Blocks: - - while (...) - { - do_something(...); - } - - if (...) - { - do_stuff(); - } - else - { - do_other_stuff(); - } diff -r 1f03f17e263e -r dde7262d0a35 TODO --- a/TODO Mon Sep 22 06:46:46 2008 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,129 +0,0 @@ -Long-term "TODO" -================ -- output plugins should have some kind of (optional) "query available formats" - function, so that the core could determine what should be used. perhaps - offer users this info? - -- remove the idiotic XMMS compatibility output plugin hack. - -- all audio plugins (input, output, effect) should be made completely - re-entrant. this probably means severely breaking the API. not very - trivial either :( - * basically plugin init() should allocate / init a state struct to - be used in all operations, etc. - - -- the equalizer should be fixed .. in more than one way: - * equalizer was broken by asphyx's libSAD - * lots of things are hardcoded, like number of EQ bands. this should - be changed. - - -- URIs with "?" are stripped (the subtune support uses that), which is bad, - because some (a lot) of real-world URLs use 'GET' arguments. this breaks - probing, but current input probing is confusing (and possibly broken anyway) - and should be refactored. - - -- mime-types support: - * there is already code for mime support, but I think it may not be - sufficient as it is designed for input plugins only -- - also playlist containers etc. need this (IMHO) - - * might be nicer to have the type registrations in plugin struct - instead of a separate function, a'la vfs_extensions. - - -- document the different APIs via Doxygen - - -- unified debugging/message system, for core and plugins - * something like glib logging system, with logging levels - * hardcoded "debugging" levels and/or macro-wrappers that would - disable superfluous debugging output compile-time. - --- being planned by ccr - - -- audacious VFS is not 64-bit offset safe, breakage will most likely occur, - if files larger than 2^31 are used (rather unlikely, tho, but still...) - - * nenolod says: current vfs sucks, it needs a "rewrite": - - buffering support - - non-blocking I/O support - - -- {core,plugins}/configure.ac need some cleanup loving. - * make session management (SM) optional. (done) - * build system cleanups .. extra.mk.in? wtf? (done in core, progressing - for plugins) - --- this is in progress, worked on by ccr - - -- plugin rewrites: - * madplug - * modplug (in progress by ccr) - * scrobbler - - -Playlist code issues -==================== -It's been determined that the playlist code should be completely refactored. - -ATTENTION! Add more stuff here! Issues that you can think of, suggestions -for solutions, etc. References to algorithms... - - -- code (mostly in playlist.c) is unnecessarily complex in some places and - there is lots of useless duplication. - -- what data structures should be used? things that factor in are - efficiency and scalability - memory usage and speed. - see also below and notice the manipulation bottleneck(s). - - (different structures typically have bottlenecks in different places.) - -- playlist_clear() is VERY slow with large playlists, possible reasons? - * GList scalability sucks? (it does, but is it the real reason here? need - to profile this...) - * maybe playlist_entry_free() is at fault instead? (see also below) - * mowgli_heap_free()? - - possible solutions? - * mempools for playlist data? not sure if possible, the tuple heaps - should then somehow be collected into pools... - * storing the playlist as a GtkTreeModel seems to be fairly fast (at least - in mudkip-player it is) --nenolod - -- current implementation has a nasty racecondition in scanner thread vs. playlist - manipulation (playlist_clear(), free, etc.) - - * new code should be water-tight when it comes to locking. simpler code - with more "atomic operations" should help. - - -ccr rants: ----------- -I suggest that the whole playlist manipulation should be moved into separate -thread. What I mean, is that the playlist scanning (e.g. probing for -metadata) AND adding files into playlist should be in a thread. - -Adding files would work like this: - 1) feed URIs to playlist handler thread - 2) playlist handler notices new URIs and starts checking if they are valid - aka probing or other checks. - 3) valid files/URIs get added to the playlist. unsupported files get discarded. - -Possible benefits of this approach: - - checking for "can we play this?", which currently happens in main - thread and blocks the GUI etc, would now happen asynchronously. - - improved user experience: less blocking generally, and it would be even - possible to _parallelize_ probing, if we wanted to, getting metadata - for multiple files at the same time. (this could be a user-settable - option.) - -Bad sides: - - requires careful design and thread locking .. but that we need anyway. - - possibly might make playlist GUI representation harder. I am not sure - what effects this might have, feel free to pitch in thoughts... - - \ No newline at end of file diff -r 1f03f17e263e -r dde7262d0a35 doc/HACKING --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/HACKING Mon Sep 22 20:14:12 2008 +0300 @@ -0,0 +1,123 @@ +Hacking / coding guide for Audacious and Audacious-plugins +========================================================== +(C) Copyright 2008 Audacious Development Team + + +Preamble +======== + +This document describes the guidelines for people who wish to work on +improving or cleaning up Audacious media player, or any of the plugins +we distribute in the plugins package. + +It is probably obvious to anyone who has taken a look into the depths +of Audacious source, that many of these guidelines are not actually +followed currently in all places, if at all. + +In fact, the purpose of this document is to act as a target to aim at, +when noticing and cleaning up uncompliant code.. or writing new code. + + +Coding guidelines +================= +- Public functions in Audacious core SHOULD be documented via Doxygen + comments! In this case "public" means any functions that span modules + OR are available to plugins. + + Of course, most functions currently lack documentation. If you have + spare time, improve the situation. + + +- We use Glib for portability. This means that we have sized integer types + such as gint{16,32,64}, etc. and shorthand types like guint and guchar + provided, so please do use them. + + Arguably C99 provides inttypes.h with similar types, but C99 support + may not be complete on all platforms, it is both safer and more uniform + to use glib types. + + +- Use other glib functionality, especially string handling like: + * g_snprintf(), g_strdup_printf(), g_strdup() ... + + +- However, avoid following Glib things: + * GString - Useless in most cases compared to normal 'C' string functions + and introduces conversions back and forth. + + * GList - GList is slow, either use GQueue or libmowgli lists. + + +- Be sure to know when you are handling UTF-8 or something else! Glib offers + special g_ascii_*() functions for certain operations that you might need + when handling non-unicode strings. + + +- When reading data from files, it's usually a BIG mistake to read structs + directly from the stream! This is not portable, as C does not guarantee + a struct not to have alignment padding (unless the struct is "packed", + but see below.) In effect sizeof(struct), unless packed, on some platform + may not be equal to some other platform. + + Making struct "packed" via the C packed qualifier or "#pragma pack()" is + a solution, but this must be used with care. Unaligned memory access + causes performance penalties, and may cause other, more serious problems + in some cases. For example, code written in assembler may not know about + the un-alignment, and may thus fail with 'bus errors' on platforms that + strictly required aligned data. + + The 100% safe way is to read individual members of the struct one by one + from the stream. This may be bothersome, but by doing so, your code + will be portable for sure. + + +- Always use Glib sized types for reading integer data from file streams. + Using plain C types (like 'long int' for example) is not wise, because + they may be of different size on different platforms depending on the + platform ABI. For example, on some 64-bit platforms, 'long int' is + 64 bits, while on 32-bit platforms it is 32 bits. + + +- Audacious core provides some helper functions for reading endian-dependant + integers from VFS streams (aud_vfs_fget_{le,be}{16,32,64}), see vfs.h and + documentation for more information. + + +- Avoid reinventing wheels, avoid code duplication. If same thing is done + in two places, it should be in a library, or possibly in Audacious core. + Discuss about it with fellow developers. + + +- In the core, DO NOT WRITE CODE THAT IS DEPENDENT ON A SPECIFIC UI OR + INTERFACE. The core should NEVER care what interface is in use. + + +Additional style guidelines +=========================== + +- Indentation: Use the same indentation style (also spaces vs. tabs) + as the file you are editing. In new files/code, use indentation of + 4 spaces (no tabs). When moving functions to new files, PLEASE + reindent the code. + +- Whitespace usage in code: + + a = 1; + + if (b == d && !strcmp(a, c)) ... + +- Blocks: + + while (...) + { + do_something(...); + } + + if (...) + { + do_stuff(); + } + else + { + do_other_stuff(); + } diff -r 1f03f17e263e -r dde7262d0a35 doc/TODO --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/TODO Mon Sep 22 20:14:12 2008 +0300 @@ -0,0 +1,129 @@ +Long-term "TODO" +================ +- output plugins should have some kind of (optional) "query available formats" + function, so that the core could determine what should be used. perhaps + offer users this info? + +- remove the idiotic XMMS compatibility output plugin hack. + +- all audio plugins (input, output, effect) should be made completely + re-entrant. this probably means severely breaking the API. not very + trivial either :( + * basically plugin init() should allocate / init a state struct to + be used in all operations, etc. + + +- the equalizer should be fixed .. in more than one way: + * equalizer was broken by asphyx's libSAD + * lots of things are hardcoded, like number of EQ bands. this should + be changed. + + +- URIs with "?" are stripped (the subtune support uses that), which is bad, + because some (a lot) of real-world URLs use 'GET' arguments. this breaks + probing, but current input probing is confusing (and possibly broken anyway) + and should be refactored. + + +- mime-types support: + * there is already code for mime support, but I think it may not be + sufficient as it is designed for input plugins only -- + also playlist containers etc. need this (IMHO) + + * might be nicer to have the type registrations in plugin struct + instead of a separate function, a'la vfs_extensions. + + +- document the different APIs via Doxygen + + +- unified debugging/message system, for core and plugins + * something like glib logging system, with logging levels + * hardcoded "debugging" levels and/or macro-wrappers that would + disable superfluous debugging output compile-time. + --- being planned by ccr + + +- audacious VFS is not 64-bit offset safe, breakage will most likely occur, + if files larger than 2^31 are used (rather unlikely, tho, but still...) + + * nenolod says: current vfs sucks, it needs a "rewrite": + - buffering support + - non-blocking I/O support + + +- {core,plugins}/configure.ac need some cleanup loving. + * make session management (SM) optional. (done) + * build system cleanups .. extra.mk.in? wtf? (done in core, progressing + for plugins) + --- this is in progress, worked on by ccr + + +- plugin rewrites: + * madplug + * modplug (in progress by ccr) + * scrobbler + + +Playlist code issues +==================== +It's been determined that the playlist code should be completely refactored. + +ATTENTION! Add more stuff here! Issues that you can think of, suggestions +for solutions, etc. References to algorithms... + + +- code (mostly in playlist.c) is unnecessarily complex in some places and + there is lots of useless duplication. + +- what data structures should be used? things that factor in are + efficiency and scalability - memory usage and speed. + see also below and notice the manipulation bottleneck(s). + + (different structures typically have bottlenecks in different places.) + +- playlist_clear() is VERY slow with large playlists, possible reasons? + * GList scalability sucks? (it does, but is it the real reason here? need + to profile this...) + * maybe playlist_entry_free() is at fault instead? (see also below) + * mowgli_heap_free()? + + possible solutions? + * mempools for playlist data? not sure if possible, the tuple heaps + should then somehow be collected into pools... + * storing the playlist as a GtkTreeModel seems to be fairly fast (at least + in mudkip-player it is) --nenolod + +- current implementation has a nasty racecondition in scanner thread vs. playlist + manipulation (playlist_clear(), free, etc.) + + * new code should be water-tight when it comes to locking. simpler code + with more "atomic operations" should help. + + +ccr rants: +---------- +I suggest that the whole playlist manipulation should be moved into separate +thread. What I mean, is that the playlist scanning (e.g. probing for +metadata) AND adding files into playlist should be in a thread. + +Adding files would work like this: + 1) feed URIs to playlist handler thread + 2) playlist handler notices new URIs and starts checking if they are valid + aka probing or other checks. + 3) valid files/URIs get added to the playlist. unsupported files get discarded. + +Possible benefits of this approach: + - checking for "can we play this?", which currently happens in main + thread and blocks the GUI etc, would now happen asynchronously. + - improved user experience: less blocking generally, and it would be even + possible to _parallelize_ probing, if we wanted to, getting metadata + for multiple files at the same time. (this could be a user-settable + option.) + +Bad sides: + - requires careful design and thread locking .. but that we need anyway. + - possibly might make playlist GUI representation harder. I am not sure + what effects this might have, feel free to pitch in thoughts... + + \ No newline at end of file