Merge branch 'master' of feistymeow.org:feisty_meow
[feisty_meow.git] / octopi / library / sockets / span_manager.h
1 #ifndef SPAN_MANAGER_CLASS
2 #define SPAN_MANAGER_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : span_manager                                                      *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 1990-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include <structures/bit_vector.h>
19
20 namespace sockets {
21
22 //! Manages lists of numbers representing the completion of some activity.
23 /*!
24   A number is either present or absent from the list.  The numbers are
25   organized according to spans, where a span is simply a range of numbers,
26   such as 33-238.  the span manager allows numbers to be added or removed
27   from the list.  it also can create the full list of either the present or
28   absent numbers.
29 */
30
31 class span_manager
32 {
33 public:
34   span_manager(int number_of_items);
35     // keeps track of "number_of_items" worth of whatever the unit is.
36
37   span_manager(const span_manager &to_copy);
38
39   ~span_manager();
40
41   span_manager &operator =(const span_manager &to_copy);
42
43   void reset(int number_of_items);
44     //!< sets up the span manager with a new configuration.
45
46   bool update(const basis::int_array &new_spans);
47     //!< updates the span information.
48     /*!< the spans listed in the hold are added to the span manager.  if the
49     spans are successfully added, then true is returned. */
50
51   int received_sequence() const;
52     //!< returns the highest chunk number at which all chunks are ready.
53     /*!< or a negative number is returned if chunk 0 has still not been
54     received yet. */
55
56   int missing_sequence() const;
57     //!< returns the number of the chunk where the first item is missing.
58     /*!< if none of them are missing, then a negative number is returned. */
59
60   void make_received_list(basis::int_array &spans, int max_spans = -1) const;
61     //!< Creates a list for the received spans that are ready.
62     /*!< The numbers in the list refer to ranges of spans fully received.  For
63     example, if 0, 3, 4, 5, 8, 9, 12, 13, 14, and 28 have been received, the
64     span list is [0-0], [3-5], [8-9], [12-14], and [28-28].  The "max_spans"
65     is the longest the list is allowed to be, unless it is negative, which
66     means include all of them. */
67
68   void make_missing_list(basis::int_array &spans, int max_spans = -1) const;
69     //!< creates a list representing the spans that are not ready yet.
70
71   const structures::bit_vector &vector() const;
72     //!< observes the held bit_vector that represents the spans.
73   structures::bit_vector &vector();
74     //!< provides access to the held bit_vector that represents the spans.
75
76   basis::astring print_received_list() const;
77     //!< prints out the span list for received blocks into a string.
78
79   basis::astring print_missing_list() const;
80     //!< prints out the span list for missing blocks into a string.
81
82 private:
83   structures::bit_vector *_implementation;  //!< our underlying structure holding spans.
84
85   basis::astring funky_print(const basis::int_array &to_spew, int rec_seq) const;
86     //!< prints the span holder to a string and returns it.
87 };
88
89 } //namespace.
90
91 #endif
92