# 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/.config/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/.config/ereswap/config
# ...providing locations for main swap, it's size, and backup swap.
# Then, run:
# /home/user/.config/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" 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"
# (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/.config/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!