changeset 4778:dde7262d0a35

Moved HACKING and TODO under doc/.

--- 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();
-  }

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

--- /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();
+  }

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