BpmDj

4.1

This page documents some aspects of the BpmDj code that are worth knowing. First and foremost is the fact that there exists a subversion repository at svn+ssh//user.org/repositories/BpmDj/ Of course you need an ssh account which can be provided if necessary.

The Development Tree
The development tree of BpmDj is somewhat different from the published (tar.gz) one. In essence, all the sources are written as c++ or h++ files (as opposed to .cpp and .h files). Each of those c++/h++ files are then converted to .cpp and .h files, which includes the copyright header and opens the proper namespace. So, if you want to edit things, you should edit the .c++ and .h++ files. However, if you want to include a specific header file in a c++ file you should use the .h file. The development tree should be kept private since it doesn't contain the proper copyright headers.

Debugging This point should be mentioned relatively early. However the background might not be that clear directly. This becomes clear later on. BpmDj starts a process that will fork off the actual application. This means that gdb-ing the main application will not make it possible for you to trace calls etcetera. There are two solutions to this.

1- Start bpmdj and connect to the second process with gdb. You do this by looking up the bpmdj pids and take the second of the two processes. Then start gdb ./bpmdj <pid> 2- Of course that approach doesn't work when bpmdj crashes. In that case use the bash process limits to ask for a core dump This is done with ulimit -c 1000000. Once the process crashed and the core dumped, you can inspect it with gdb ./bpmdj core.55318 (or whatever it is called at your setup).

Types
BpmDj relies on types of a specific size. These are directly reflected with a number such that we know how many bytes that type takes. For instance unsigned8 is an unsigned long integer of 8 bytes (=64 bits) unsigned4 is an unsigned byte of 4 bytes long (=16 bit). There exist signed1, signed2, signed4, signed8, unsigned1, unsigned2, unsigned4, unsigned8 and float4 and float8. When writing source please use these types since it makes porting BpmDj to different architectures much easier. To get access to these basic types you can include "types.h"

Processes and threads Process management and Thread management in BpmDj is complicated. Not because it is designed to be complicated, but rather because process management brings with it a bunch of concurrency problems for free. Certainly so because

• X doesn't like concurrent access from different processes
• Qt insists on running in the main thread and should never be accessed from any other thread
• forking off processes while an ALSA PCM device is open will screw up the alsa file descriptors
• signalling more than 2 dead process will ensure that one process id gets lost
• etcetera. There was just no end to the process/thread based concurrency problems. To avoid these we make a distinction between Processes and Active Objects Active objects (these can be compared to threads that receive and handle messages, except without the concurrency problems). There are few processes. Currently these are

• bpmdj: the main program, which is the selector
• bpmdj the overseer thread, which is responsible for starting processes and tracking their state.
• bpmplay which is a process that plays one song. Typically two bpmplay processes are running at the same time.
• bpmdjraw although this is a simply script, it is forked off from a bpmplay player. This scripts is responsible for decoding the mp3 files.
• bpmclock to provide an external clock whenever wanted

Active objects in BpmDj:

• a song copier (ActiveSongCopier), which will take a collection of songs and copy them to a target directory.
• an existence scanner: ActiveExistenceScanner, which goes through the music directory and checks which files exist.
• a fragment player: ActiveFragmentPlayer, which will play a fragment when it is ready. The fragment player also opens the appropriate DSP device.
• a fragment creator: ActiveFragmentCreator, which keeps track of the fragments the user might wish to listen to and decodes them. The fragment creator will spawn off the necessary processes.
• a Principal Component Analysis process: ActiveSpectrumPca, which analyzes the sound color of all songs after all the indices have been read in memory.
• an Index Reader: ActiveIndexReader, which will scan the index directory and read in the entire database.
• a cluster analysis algorithm, ActiveCluster, which runs through a selection of songs and groups them together based on the current distance metric.
• An active object which keeps track of all existing active objects: the ActiveAoTracker.

Data management BpmDj relies on two techniques to deal with data. The first is a library that deals with reference counting of objects that are passed along. These are important for the active objects since the reference counting must be threadsafe and deallocation can no longer be expected at a fixed point in the source. The second aspect of data management is the use of a Data abstraction layer. This is mainly responsible for saving and loading data to disk through a class called Index. The ActiveIndexReader takes care to actually read in the database.

Code style The coding style for block is that each { or } is placed on an individual line. Lines are 80 characters long.

Write your own compiler Whenever the same task must be written many times it is a good idea to think about writing a compiler that will write the source for you. This avoids mistakes in the handwritten code and in general either works like a charm or crashes eveyrwhere. This is demonstated through the active objects library.