task.hh

Go to the documentation of this file.

// -*- c-basic-offset: 4; related-file-name: "../../lib/task.cc" -*-
#ifndef CLICK_TASK_HH
#define CLICK_TASK_HH
#include <click/element.hh>
#include <click/sync.hh>
#if HAVE_MULTITHREAD
# include <click/atomic.hh>
# include <click/ewma.hh>
#endif
CLICK_DECLS
 
#if CLICK_BSDMODULE
# include <click/cxxprotect.h>
CLICK_CXX_PROTECT
# include <sys/lock.h>
# include <sys/mutex.h>
CLICK_CXX_UNPROTECT
# include <click/cxxunprotect.h>
#else
#define GIANT_REQUIRED
#endif
 
#define PASS_GT(a, b)   ((int)(a - b) > 0)
 
typedef bool (*TaskCallback)(Task *, void *);
typedef TaskCallback TaskHook CLICK_DEPRECATED;
class RouterThread;
class TaskList;
class Master;
 
struct TaskLink {
#if !HAVE_TASK_HEAP
    TaskLink *_prev;
    TaskLink *_next;
#endif
#if HAVE_STRIDE_SCHED
    unsigned _pass;
#endif
    TaskLink() {
#if !HAVE_TASK_HEAP
        _prev = _next = 0;
#endif
#if HAVE_STRIDE_SCHED
        _pass = 0;
#endif
    }
};
 
class Task : private TaskLink { public:
 
#if HAVE_STRIDE_SCHED
    enum { STRIDE1 = 1U<<16, MAX_STRIDE = 1U<<31 };
    enum { MAX_TICKETS = 1<<15, DEFAULT_TICKETS = 1<<10 };
#endif
#if HAVE_ADAPTIVE_SCHEDULER
    enum { MAX_UTILIZATION = 1000 };
#endif
 
    inline Task(TaskCallback f, void *user_data, int tid = -2);
 
    inline Task(Element *e);
 
    ~Task();
 
 
    inline TaskCallback callback() const {
        return _hook;
    }
 
    inline void *user_data() const {
        return _thunk;
    }
 
    inline Element *element() const {
        return _owner;
    }
 
 
    inline bool initialized() const;
 
    inline int home_thread_id() const;
 
    inline RouterThread *thread() const;
 
    inline Router *router() const {
        return _owner->router();
    }
 
    Master *master() const;
 
 
    void initialize(Element *owner, bool schedule);
 
    void initialize(Router *router, bool schedule);
 
 
    inline bool scheduled() const {
        return _status.is_scheduled;
    }
 
 
    inline void unschedule() {
        _status.is_scheduled = false;
    }
 
    void unschedule_notify(Element* e);
 
    inline void reschedule() {
        _status.is_scheduled = true;
        click_fence();
        if (_pending_nextptr.x < 2)
            complete_schedule(0);
    }
 
    void reschedule_notify(Element* e);
 
    inline void fast_reschedule() {
        _status.is_scheduled = true;
    }
 
 
    inline void strong_unschedule() {
        _status.is_scheduled = false;
        _status.is_strong_unscheduled = true;
    }
 
    inline void strong_reschedule() {
        _status.is_strong_unscheduled = false;
        reschedule();
    }
 
 
    void move_thread(int new_thread_id);
 
 
#if HAVE_STRIDE_SCHED
    inline int tickets() const;
    inline void set_tickets(int n);
    inline void adjust_tickets(int delta);
#endif
 
    inline bool fire();
 
#if HAVE_ADAPTIVE_SCHEDULER
    inline unsigned runs() const;
    inline unsigned work_done() const;
    inline unsigned utilization() const;
    inline void clear_runs();
#endif
#if HAVE_TASK_STATS
    inline int cycles() const;
    inline unsigned cycle_runs() const;
    inline void update_cycles(unsigned c);
#endif
 
    inline TaskCallback hook() const CLICK_DEPRECATED;
    inline void *thunk() const CLICK_DEPRECATED;
  private:
 
#if HAVE_TASK_HEAP
    int _schedpos;
#endif
 
#if HAVE_STRIDE_SCHED
    unsigned _stride;
    int _tickets;
#endif
 
    union Status {
        struct {
            int16_t home_thread_id;
            uint8_t is_scheduled;
            uint8_t is_strong_unscheduled;
        };
        uint32_t status;
    } _status;
 
    TaskCallback _hook;
    void *_thunk;
 
#if HAVE_ADAPTIVE_SCHEDULER
    unsigned _runs;
    unsigned _work_done;
#endif
#if HAVE_TASK_STATS
    DirectEWMA _cycles;
    unsigned _cycle_runs;
#endif
 
    RouterThread *_thread;
 
    Element *_owner;
 
    union Pending {
        Task *t;
        uintptr_t x;
    };
    Pending _pending_nextptr;
 
    Task(const Task &x);
    Task &operator=(const Task &x);
    void cleanup();
 
#if CLICK_DEBUG_SCHEDULING
 public:
#endif
    inline bool on_scheduled_list() const;
    inline bool on_pending_list() const {
        return _pending_nextptr.x != 0;
    }
    inline bool needs_cleanup() const;
#if CLICK_DEBUG_SCHEDULING
 private:
#endif
 
    void add_pending(bool always);
    void process_pending(RouterThread* thread);
 
    void complete_schedule(RouterThread* process_pending_thread);
    inline void remove_from_scheduled_list();
 
    static bool error_hook(Task *task, void *user_data);
 
    friend class RouterThread;
    friend class Master;
};
 
 
// need RouterThread's definition for inline functions
CLICK_ENDDECLS
#include <click/routerthread.hh>
CLICK_DECLS
 
 
inline
Task::Task(TaskCallback f, void *user_data, int tid)
    :
#if HAVE_TASK_HEAP
      _schedpos(-1),
#endif
#if HAVE_STRIDE_SCHED
      _stride(0), _tickets(-1),
#endif
      _hook(f), _thunk(user_data),
#if HAVE_ADAPTIVE_SCHEDULER
      _runs(0), _work_done(0),
#endif
#if HAVE_TASK_STATS
      _cycle_runs(0),
#endif
      _thread(0), _owner(0)
{
    _status.home_thread_id = tid;
    _status.is_scheduled = _status.is_strong_unscheduled = false;
    _pending_nextptr.x = 0;
}
 
inline
Task::Task(Element* e)
    :
#if HAVE_TASK_HEAP
      _schedpos(-1),
#endif
#if HAVE_STRIDE_SCHED
      _stride(0), _tickets(-1),
#endif
      _hook(0), _thunk(e),
#if HAVE_ADAPTIVE_SCHEDULER
      _runs(0), _work_done(0),
#endif
#if HAVE_TASK_STATS
      _cycle_runs(0),
#endif
      _thread(0), _owner(0)
{
    _status.home_thread_id = -2;
    _status.is_scheduled = _status.is_strong_unscheduled = false;
    _pending_nextptr.x = 0;
}
 
inline bool
Task::initialized() const
{
    return _owner != 0;
}
 
inline bool
Task::on_scheduled_list() const
{
#if HAVE_TASK_HEAP
    return _schedpos >= 0;
#else
    return _prev != 0;
#endif
}
 
inline bool
Task::needs_cleanup() const
{
#if HAVE_TASK_HEAP
    int a;
    uintptr_t b;
    do {
        a = _schedpos;
        b = _pending_nextptr.x;
        click_fence();
    } while (a != _schedpos || b != _pending_nextptr.x);
    return a >= 0 || b != 0;
#else
    TaskLink* a;
    uintptr_t b;
    do {
        a = _prev;
        b = _pending_nextptr.x;
        click_fence();
    } while (a != _prev || b != _pending_nextptr.x);
    return a != 0 || b != 0;
#endif
}
 
inline TaskCallback
Task::hook() const
{
    return _hook;
}
 
inline void *
Task::thunk() const
{
    return _thunk;
}
inline int
Task::home_thread_id() const
{
    return _status.home_thread_id;
}
 
inline RouterThread *
Task::thread() const
{
    return _thread;
}
 
inline void
Task::remove_from_scheduled_list()
{
    if (on_scheduled_list()) {
#if HAVE_TASK_HEAP
        Task *back = _thread->_task_heap.back().t;
        _thread->_task_heap.pop_back();
        if (_thread->_task_heap.size() > 0)
            _thread->task_reheapify_from(_schedpos, back);
        click_fence();
        _schedpos = -1;
#else
        _next->_prev = _prev;
        _prev->_next = _next;
        _next = 0;
        click_fence();
        _prev = 0;
#endif
    }
}
 
#if HAVE_STRIDE_SCHED
 
inline int
Task::tickets() const
{
    return _tickets;
}
 
inline void
Task::set_tickets(int n)
{
    if (n > MAX_TICKETS)
        n = MAX_TICKETS;
    else if (n < 1)
        n = 1;
    _tickets = n;
    _stride = STRIDE1 / n;
    assert(_stride < MAX_STRIDE);
}
 
inline void
Task::adjust_tickets(int delta)
{
    set_tickets(_tickets + delta);
}
 
#endif /* HAVE_STRIDE_SCHED */
 
 
inline bool
Task::fire()
{
#if CLICK_STATS >= 2
    click_cycles_t start_cycles = click_get_cycles(),
        start_child_cycles = _owner->_child_cycles;
#endif
#if HAVE_TASK_STATS
    _cycle_runs++;
#endif
    bool work_done;
    if (!_hook)
        work_done = ((Element*)_thunk)->run_task(this);
    else
        work_done = _hook(this, _thunk);
#if HAVE_ADAPTIVE_SCHEDULER
    ++_runs;
    _work_done += work_done;
#endif
#if CLICK_STATS >= 2
    click_cycles_t all_delta = click_get_cycles() - start_cycles,
        own_delta = all_delta - (_owner->_child_cycles - start_child_cycles);
    _owner->_task_calls += 1;
    _owner->_task_own_cycles += own_delta;
#endif
    return work_done;
}
 
#if HAVE_ADAPTIVE_SCHEDULER
inline unsigned
Task::runs() const
{
    return _runs;
}
 
inline unsigned
Task::work_done() const
{
    return _work_done;
}
 
inline unsigned
Task::utilization() const
{
    return (_runs ? (MAX_UTILIZATION * _work_done) / _runs : 0);
}
 
inline void
Task::clear_runs()
{
    _runs = _work_done = 0;
}
#endif
 
#if HAVE_TASK_STATS
inline int
Task::cycles() const
{
    return _cycles.unscaled_average();
}
 
inline unsigned
Task::cycle_runs() const
{
    return _cycle_runs;
}
 
inline void
Task::update_cycles(unsigned c)
{
    _cycles.update(c);
    _cycle_runs = 0;
}
#endif
 
CLICK_ENDDECLS
#endif