Napi api: Batch API

Well, talán harmadjára futok össze a batch apival, és még mindig nem volt zökkenőmentes a barátság, szóval amíg az a betyár sok elem leszalad, amin dolgoztam, levésem gyorsan a tudnivalókat, hogy legközelebb már ne kelljen megint mindenre rájönni.

No akkor batch api:

A batch kötegelt feldolgozást jelent. Drupalon belül úgy is mondhatjuk, hogyha egyszerre annyi adattal kell dolgozni, ami túlnő egy oldalletöltés korlátjain, akkor kell a batch apihoz nyúlni. A képet megnézve valószínű egyébként, hogy egyből leesik, a Drupal melyik részéről is van szó.

Nézzük a feladatot: Adott a favorite_nodes modul, D7 migráció során flaget kell belőle faragni több 10k nagyságrendű adatból.

A batch api maga két fő részből áll. Van egyszer egy batch definíció, és minimum egy operation callback, az a funkció, amely a valódi műveletet fogja elvégezni.

Így néz ki nagyjából egy batch definíció:

  $batch = array(
    'operations' => array(
      array('operation_callback', array())
    ),
    'finished' => 'favorite_nodes_to_flag_batch_finished',
    'title' => t('Convert all favorite nodes to flag'),
    'init_message' => t('Convert starting..'),
    'progress_message' => t('Processed @current out of @total.'),
    'error_message' => t('Hmm.. Something could be wrong, sorry, post an issue to module..'),
  );

Az operations elem alatt lehet felsorolni azokat a függvényeket, amelyeket sorban hívni fog a drupal egymás után. Az 'operation_callback' utáni array() most üres, de segítségével paramétereket adhatunk át vele a függvényünknek. Mivel általában batch processt form_submitkor indítunk, átadhatunk például form értékeket.

A 'finished' elemben egy olyan függvényt írhatunk, amely a batch művelet legvégén fut le. Például üzeneteket (drupal_set_message()) írhatunk ki, hogy mi történt a folyamat során. Figyi, ez nem array, ebből csak egy van!

Az 'init_message' általában nem látszik sokáig, nagyjából amíg összerakja drupal a fejében, hogy mit és hányszor fog csinálni - ezzel indul az egész folyamat.

Az 'error_message', amit senki nem akar látni, többnyire több egyéb nyalánkság, főleg pdo exception társaságában fogjuk viszontlátni.

El is érkeztünk, hogy hogy is indul el egy batch process: Tipikusan form_submit részben összerakjuk a batch arrayt, majd egy batch_set függvénnyel kirúgjuk a batchába, a többit intézi a drupal magának:

function my_module_form_submit($form, &$form_state) {
  $batch = array(lásd felül);
  batch_set($batch);
}

Ezzel elkezdődik az operation része a batchnek. Ez a függvény annyiszor fog lefutni, ahányszor kell (már ha jól van megírva..)
Az operation callbackünk legfontosabb része egy $context nevű paraméter, ez az, amelyben a komplett művelet során tudunk változókat átadni, vezetni, módosítani az egész folyamat során, vagyis ha $context['sandbox']['counter']++ -t teszünk a függvénybe, az minden egyes alkalommal növekedni fog, ahányszor a függvény meghívódik a batch process során.

Ennek a $context paraméternek a következő részeit állítgathatjuk:

$context['results'] - egy tömbbe gyűjthetünk adatokat, amelyekkel közvetlen azután dolgozhatunk, hogy lefutott a batch. Ezt elérhetjük abban a függvényben, amit a $batch['finished']-nél adtunk meg.

$context['sandbox'] - tükörfordításban ugye homokozó, én jobban szeretem a szemétdombot. Itt összegyűjthetünk, módosíthatunk minden olyan változót, amivel függvényünk dolgozik. Például ahogy fentebb is volt már, hogy hányszor futott a process.

$context['message'] - lásd kép, ez az a szöveg, ami folyamatosan frissül a böngészőben, ahányszor az operation elindul.

$context['finished'] - Hogy hány %-nál jár a művelet. Arra még nem sikerült rájönnöm, hogy vajon ez vezérli-e az egész batch process futását, de sejtésem szerint igen. Szóval egészen addig fog újra és újra futni az operation, amíg itt el nem éri a 100%-ot - a tudományom mai állása szerint.

Nézzünk egy ilyen függvényt, és magyarázzunk:

function MODULOM_batch_operation(&$context) {
  // Az első futásnál ez a $context['sandbox'] üres
  // Ilyenkor kell feltölteni inicializálni pár dolgot
  if (empty($context['sandbox'])) {
    // Ez lesz most a számlálónk, vagyis hogy hány elemet dolgoztunk fel.
    $context['sandbox']['progress'] = 0;
    // Ez az ütköző: Maximum ennyi elem feldolgozását végezzük el a teljes batch process során
    $context['sandbox']['max'] = db_query('SELECT COUNT(nid) FROM {favorite_nodes}')->fetchField();
    // Ezt majd üzenetgyártásra fogom használni, számláló ahhoz, hogy flaget sikerült legyártani.
    $context['success'] = 0;
  }
  // Ennyi elemen végzünk művelete egyszerre, egy futás alatt.
  $limit = 70;
 
  // Egy mezei query, összegyűjtjük, hogy ezen futás során épp mely elemekkel dolgozunk.
  // Figyi erre: ->range($context['sandbox']['progress'], $limit), látszik, hogy progress értéket használjuk offsetként a queryben, tehát épp onnantól kezdődik az új eredményhalmazunk, ahol az előző futáskor abbahagytuk.
  $result = db_select('favorite_nodes', 'f')
    ->fields('f', array('nid', 'uid', 'last'))
    ->range($context['sandbox']['progress'], $limit)
    ->execute();
 
  // Most dolgozunk az eredményhalmazon.
  foreach ($result as $row) {
    // Először növeljük a progresst.
    $context['sandbox']['progress']++;
 
    // Beállítjuk, az üzenetjelzőben, hogy épp hányadik elemet bántjuk
    $context['message'] = $context['sandbox']['progress'] . ' item processed.';
 
    // Ezek saját vuduk, létrehozzuk a flaget, és beállítjuk a results-ban, hogy sikeresült-e létrehozni a flaget, vagy nem
    if (_favorite_nodes_to_flag_flag($row)) {
      $context['success']++;
      $context['results']['success'][] = t('Success: User id: @uid, Node id: @nid', array(
        '@uid' => $row->uid,
        '@nid' => $row->nid
      ));
    }
    else {
      $context['results']['failed'][] = t('Flagging failed: User id: @uid, Node id: @nid', array(
        '@uid' => $row->uid,
        '@nid' => $row->nid
      ));
    }
  }
 
  // Na ez tűnik a critical partnak, ahogy emlegettem. Ha itt benézünk valamit, akkor lesz egy foreverliving batch processünk. Szóval figyeljünk, hogy hogyan állítjuk be az ütközőt.
  if ($context['sandbox']['progress'] != $context['sandbox']['max']) {
    $context['finished'] = $context['sandbox']['progress'] / $context['sandbox']['max'];
  }
}

Ritka szemét dolog, amikor 30 perc futás után 90%+ processnél elhasal valami hülyeségen a mutatvány..