apps/include/cdi/cache.h

   1 /*
   2  * Copyright (c) 2008 Antoine Kaufmann
   3  *
   4  * This program is free software. It comes without any warranty, to
   5  * the extent permitted by applicable law. You can redistribute it
   6  * and/or modify it under the terms of the Do What The Fuck You Want
   7  * To Public License, Version 2, as published by Sam Hocevar. See
   8  * http://sam.zoy.org/projects/COPYING.WTFPL for more details.
   9  */
  10
  11 #ifndef _CDI_CACHE_H_
  12 #define _CDI_CACHE_H_
  13
  14 #include <stdint.h>
  15
  16 struct cdi_cache {
  17     /** Groesse der Blocks, die der Cache verwaltet */
  18     size_t      block_size;
  19
  20     /* OS-Spezifische Daten folgen... */
  21 };
  22
  23 /** Block fuer direkten, schnellen Zugriff. */
  24 struct cdi_cache_block {
  25     /** Blocknummer */
  26     uint64_t    number;
  27
  28     /** Zeiger auf die Daten */
  29     void*       data;
  30
  31     /** Pointer auf blkpriv_len Bytes, die vom Aufrufer benutzt werden koennen*/
  32     void*       private;
  33 };
  34
  35 /** Typ fuer Cache-Callback zum einlesen eines Blocks. */
  36 typedef int (cdi_cache_read_block_t)(struct cdi_cache* cache, uint64_t block,
  37     size_t count, void* dest, void* prv);
  38
  39 /** Typ fuer Cache-Callback zum schreiben eines Blocks. */
  40 typedef int (cdi_cache_write_block_t)(struct cdi_cache* cache, uint64_t block,
  41     size_t count, const void* src, void* prv);
  42
  43
  44 /**
  45  * Cache erstellen
  46  *
  47  * @param block_size    Groesse der Blocks die der Cache verwalten soll
  48  * @param blkpriv_len   Groesse der privaten Daten die fuer jeden Block
  49  *                      alloziert werden und danach vom aurfrufer frei benutzt
  50  *                      werden duerfen
  51  * @param read_block    Funktionspointer auf eine Funktion zum einlesen eines
  52  *                      Blocks.
  53  * @param write_block   Funktionspointer auf eine Funktion zum schreiben einses
  54  *                      Blocks.
  55  * @param prv_data      Wird den Callbacks als letzter Parameter uebergeben
  56  *
  57  * @return Pointer auf das Cache-Handle
  58  */
  59 struct cdi_cache* cdi_cache_create(size_t block_size, size_t blkpriv_len,
  60     cdi_cache_read_block_t* read_block,
  61     cdi_cache_write_block_t* write_block,
  62     void* prv_data);
  63
  64 /**
  65  * Cache zerstoeren
  66  */
  67 void cdi_cache_destroy(struct cdi_cache* cache);
  68
  69 /**
  70  * Veraenderte Cache-Blocks auf die Platte schreiben
  71  *
  72  * @return 1 bei Erfolg, 0 im Fehlerfall
  73  */
  74 int cdi_cache_sync(struct cdi_cache* cache);
  75
  76 /**
  77  * Cache-Block holen. Dabei wird intern ein Referenzzaehler erhoeht, sodass der
  78  * Block nicht freigegeben wird, solange er benutzt wird. Das heisst aber auch,
  79  * dass der Block nach der Benutzung wieder freigegeben werden muss, da sonst
  80  * die freien Blocks ausgehen.
  81  *
  82  * @param cache     Cache-Handle
  83  * @param blocknum  Blocknummer
  84  *
  85  * @return Pointer auf das Block-Handle oder NULL im Fehlerfall
  86  */
  87 struct cdi_cache_block* cdi_cache_block_get(struct cdi_cache* cache,
  88     uint64_t blocknum);
  89
  90 /**
  91  * Cache-Block freigeben
  92  *
  93  * @param cache Cache-Handle
  94  * @param block Block-Handle
  95  */
  96 void cdi_cache_block_release(struct cdi_cache* cache,
  97     struct cdi_cache_block* block);
  98
  99 /**
 100  * Cache-Block als veraendert markieren
 101  *
 102  * @param cache Cache-Handle
 103  * @param block Block-Handle
 104  */
 105 void cdi_cache_block_dirty(struct cdi_cache* cache,
 106     struct cdi_cache_block* block);
 107
 108 #endif