# ereswap readme file

# ereswap is a set of scripts, allowing to detect swap fragmentation,
# and to refresh swap by re-enabling it, when needed (or doing the
# latter no matter of conditions, if user decide to).
# 
# Swap fragmentation starts to occur, when total number of megabytes
# written during swap's life time exceed it's maximum size. Until that,
# swap is written in purely sequential manner (blocks that are no
# longer needed, are marked as free, but never used) - hoever, after
# reaching end of swap space, previously used free blocks are written
# again, using new content. This mean no longer writing sequentially,
# causing massive slowdowns, while using already slow (compared to RAM)
# swap. A workaround to this is disabling and enabling swap again -
# linuxswap filesystem content doesn't live through reboots, and once
# re-enabled, is written sequentially again.
#
# ereswap achieve it, by counting - via iostat - number of megabytes
# saved to swap partition during runtime (*not* current swap usage)
# and comparing it to adjacent number during last reswap (or boot).
# If it's higher than set value, swap is re-enabled, and user
# informed via Maemo notification system. In case of failure, the same
# notification system is used to inform user about step, that created
# problems.
#
# location of swap partitions and number of written megabytes setting
# swap as valid for reswap are configurable via
# /home/user/.ereswap/config file.
#
# To work properly, ereswap require existence of 2 swap partitions (on
# microSD or eMMC, all combinations allowed). For maximum performance
# of Maemo, using swap on microSD *only* and keeping backup, unused
# swap on eMMC is recommended - the later can be default one, or
# anything of 100MB minimum size (in case someone want to repartition
# and reclaim space for other partitions).
#
# ereswap is terminal tool as-is, but user can easily create a
# .desktop shortcut for it, invoke via QueenBeeconWidget, shortcutd,
# etc. ereswap is easily customizable and extendable - frontend for it
# could be easily written in any language supported by Maemo. It can be
# also integrated into other programs with minimum effort required.
#
# ereswap is licensed under terms of GPL. It's based on concept and
# (partially) scripts by shadowjk (thanks a lot!)
#
# Usage:
# After installation, edit:
# /home/user/.ereswap/config
# ...providing locations for main swap, it's size, and backup swap. Then, run:
# /home/user/.ereswap/adjust-rcS-late.sh
# It will adjust Your "/etc/event.d/rcS-late", to - during boot - enable Your main swap and to reset Mb-written-to-swap counter. This step must be done only once.
#
# Now, at any time, invoke "ereswap.sh" from terminal. It will check counter and inform You about ammount of data left before hitting swap fragmentation (or any arbitrary value set in config file), or, how many Mb's after it You are. In second case, it will also re-enable swap.
# To re-enable swap at any time, unconditionaly, invoke "freswap.sh" (useful, if You're close to hit limit, and planning to do memory-hungry stuff).
# 
# If You ever change Your swap's location, just edit config file and invoke:
# /home/user/.ereswap/update-rcS-late.sh
#
# ---
# 
# Thanks to shadowjk for swap refreshing concept and proof-of-concept script.
# Thanks to Hurrian for pointing to a concept of backup swap mechanism in rcS-late, created by GameboyRMH.
# Huge thanks for merlin1991 (also for packaging), DocScrutinizer, Sicelo and everyone else answering my countless questions and providing working code samples on #maemo. Guys, You rox!
# Especially huge thanks for Sc0rpius, for sitting with me for hours and working to fix sed's commands in update/adjust-rcS-late.sh scripts. I would be nowhere, without Your help!