The following text is from the introduction of the HOWTO I’ve
written explaining how to modify a program to use Woodchuck. The
focus is on the Python interface, but it should be helpful to anyone
who wants to modify an application to use Woodchuck. This document,
unlike the detailed documentation, should be a bit easier to
digest if you are just getting started with Woodchuck. If questions
still remain, feel free to email me or ask for help on #woodchuck on
Woodchuck is a framework for scheduling the transmission of delay
tolerant data, such as RSS feeds, email and software updates.
Woodchuck aims to maximize data availability (the probability that the
data the user wants is accessible) while minimizing the incurred costs
(in particular, data transfer charges and battery energy consumed).
By scheduling data transfers when conditions are good, Woodchuck
ensures that data subscriptions are up to date while saving battery
power, reducing the impact of data caps and hiding spotty network
At the core of Woodchuck is a daemon. This centralized service
reduces redundant work and facilitates coordination of shared
resources. Redundant work is reduced because only a single entity
needs to monitor network connectivity and system activity. Further,
because the daemon starts applications when they should perform a
transfer, applications do not need to wait in the background to
perform automatic updates thereby freeing system resources. With
respect to the coordination of shared resources: the cellular data
transmission budget and the space allocated for prefetched data need
to be allocated among the various programs.
Applications need to be modified to benefit from Woodchuck. Woodchuck
needs to know about the streams that the user has subscribed to and
the objects which they contain as well as related information such as
an object’s publication time. Woodchuck also needs to be able to
trigger data transfers. Finally, Woodchuck’s scheduler benefits from
knowing when the user accesses objects. In my experience, the changes
required are relatively non-invasive and not difficult. This largely
depends, however, on the structure of the application.
I designed Woodchuck’s API to be easy to use. A major goal was to
allow applications to progressively add support for Woodchuck: it
should be possible to add minimal Woodchuck support and gain some
benefit of the services that Woodchuck offers; more complete support
results in higher-quality service.
To support Woodchuck, an application needs to do three things:
- register streams and objects;
- process upcalls: update a stream, transfer an object, and,
optionally, delete an object’s files; and,
- send feedback: report stream updates, object downloads and object
The rest of this document is written as a tutorial that assumes that
you are using PyWoodchuck, the Python interface to Woodchuck. If you
are using libgwoodchuck, a C interface, or the low-level DBus
interface, this document is still a good starting point for
understanding what your application needs to do.