disorder.h: more consistent approach to function attributes

[disorder] / lib / queue.h

diff --git a/lib/queue.h b/lib/queue.h
index 6baf9162c6b265173938e6b4b1f363f12634c6e2..9bad76e11d6b9b6658583d7aad0e16695b0e7937 100644 (file)
--- a/lib/queue.h
+++ b/lib/queue.h
@@ -1,6 +1,6 @@
 /*
  * This file is part of DisOrder.
- * Copyright (C) 2004-2008 Richard Kettlewell
+ * Copyright (C) 2004-2009 Richard Kettlewell
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -31,15 +31,16 @@ enum playing_state {
   /** @brief Track failed to play */
   playing_failed,
 
-  /** @brief Track is a scratch and has not been played yet
+  /** @brief OBSOLETE
    *
-   * Going to become obsolete.
+   * Formerly denoted an unplayed scratch.  This is now indicated by @p
+   * playing_unplayed and @p origin_scratch.
    */
   playing_isscratch,
 
-  /** @brief Could not find a player
+  /** @brief OBSOLETE
    *
-   * Obsolete - nothing sets this any more
+   * Formerly meant that no player could be found.  Nothing sets this any more.
    */
   playing_no_player,
 
@@ -60,10 +61,11 @@ enum playing_state {
   /** @brief Track is playing but the server is quitting */
   playing_quitting,
 
-  /** @brief Track was randomly chosen and has not been played
+  /** @brief OBSOLETE
    *
-   * This is going to become obsolete eventually; it's equivalent to @ref
-   * playing_unplayed but for tracks with a different origin.
+   * Formerly this meant a track that was picked at random and has not yet been
+   * played.  This situation is now indicated by @p playing_unplayed and @p
+   * origin_random (or @p origin_adopted).
    */
   playing_random,
 
@@ -92,8 +94,7 @@ extern const char *const playing_states[];
 enum track_origin {
   /** @brief Track was picked at random and then adopted by a user
    *
-   * @c submitter identifies who adopted it.  This isn't implemented
-   * yet.
+   * @c submitter identifies who adopted it.
    */
   origin_adopted,
 
@@ -187,7 +188,21 @@ struct queue_entry {
   /** @brief How much of track has been played so far (seconds) */
   long sofar;
 
-  /** @brief True if decoder is connected to speaker */
+  /** @brief True if track preparation is underway
+   *
+   * This is set when a decoder has been started and is expected to connect to
+   * the speaker, but the speaker has not sent as @ref SM_ARRIVED message back
+   * yet. */
+  int preparing;
+
+  /** @brief True if decoder is connected to speaker 
+   *
+   * This is not a @ref playing_state for a couple of reasons
+   * - it is orthogonal to @ref playing_started and @ref playing_unplayed
+   * - it would have to be hidden to other users of @c queue_entry
+   *
+   * For non-raw tracks this should always be zero.
+   */
   int prepared;
   /* For DISORDER_PLAYER_PAUSES only: */
 
@@ -202,6 +217,15 @@ struct queue_entry {
 
   /** @brief Owning queue (for Disobedience only) */
   struct queuelike *ql;
+  
+  /** @brief Decoder (or player) process ID */
+  pid_t pid;
+
+  /** @brief Termination signal sent to subprocess
+   *
+   * Used to supress 'terminated' messages.
+   */
+  int killed;
 };
 
 void queue_insert_entry(struct queue_entry *b, struct queue_entry *n);
@@ -220,6 +244,8 @@ int queue_unmarshall_vec(struct queue_entry *q, int nvec, char **vec,
 char *queue_marshall(const struct queue_entry *q);
 /* marshall @q@ into a UTF-8 string */
 
+void queue_free(struct queue_entry *q, int rest);
+
 #endif /* QUEUE_H */
 
 /*