Introduce Batching

composer.json

@@ -85,6 +85,9 @@
     "scripts": {
         "google-cloud": "dev/google-cloud"
     },
+    "bin": [
+        "src/Core/bin/google-cloud-batch"
+    ],
     "extra": {
         "component": {
             "id": "google-cloud",

dev/sh/clear-ipc

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+set -ev
+
+ipcs -m | grep `whoami` | awk '{ print $2 }' | xargs -n1 ipcrm -m
+ipcs -s | grep `whoami` | awk '{ print $2 }' | xargs -n1 ipcrm -s
+ipcs -q | grep `whoami` | awk '{ print $2 }' | xargs -n1 ipcrm -q

dev/src/DocGenerator/DocGenerator.php

@@ -97,17 +97,18 @@ public function generate($basePath, $pretty)
             }
 
             $document = $parser->parse();
+            if ($document) {
+                $writer = new Writer($document, $this->outputPath, $pretty);
+                $writer->write($currentFile);
 
-            $writer = new Writer($document, $this->outputPath, $pretty);
-            $writer->write($currentFile);
-
-            $this->types->addType([
-                'id' => $document['id'],
-                'title' => $document['title'],
-                'contents' => ($this->isComponent)
-                    ? $this->prune($document['id'] . '.json')
-                    : $document['id'] . '.json'
-            ]);
+                $this->types->addType([
+                    'id' => $document['id'],
+                    'title' => $document['title'],
+                    'contents' => ($this->isComponent)
+                        ? $this->prune($document['id'] . '.json')
+                        : $document['id'] . '.json'
+                ]);
+            }
         }
     }
 

dev/src/DocGenerator/Parser/CodeParser.php

@@ -69,7 +69,11 @@ public function __construct(
     public function parse()
     {
         $this->reflector->process();
-        return $this->buildDocument($this->getReflector($this->reflector));
+        $reflector = $this->getReflector($this->reflector);
+
+        return $reflector
+            ? $this->buildDocument($reflector)
+            : null;
     }
 
     private function getReflector($fileReflector)
@@ -86,7 +90,7 @@ private function getReflector($fileReflector)
             return $fileReflector->getTraits()[0];
         }
 
-        throw new \Exception('Could not get reflector for '. $this->fileName);
+        return null;
     }
 
     private function buildDocument($reflector)

dev/src/Snippet/Parser/Parser.php

@@ -137,14 +137,16 @@ public function examplesFromClass($class)
             $methods = $this->buildMagicMethods($magicMethods, $class->getName());
 
             foreach ($methods as $method) {
-                $res = current($this->examples(
+                $magicExamples = $this->examples(
                     $method['doc'],
                     $class->getName() .'::'. $method['name'],
                     $class->getFileName(),
                     $class->getStartLine()
-                ));
+                );
 
-                $magic[$res->identifier()] = $res;
+                foreach ($magicExamples as $ex) {
+                    $magic[$ex->identifier()] = $ex;
+                }
             }
         }
 

src/Core/Batch/BatchConfig.php

@@ -0,0 +1,113 @@
+<?php
+/**
+ * Copyright 2017 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Google\Cloud\Core\Batch;
+
+/**
+ * Hold configurations for the {@see \Google\Cloud\Core\Batch\BatchRunner}.
+ */
+class BatchConfig
+{
+    /**
+     * @var BatchJob[]
+     */
+    private $jobs = [];
+
+    /**
+     * @var array
+     */
+    private $idmap = [];
+
+    /**
+     * @var array
+     */
+    private $idmap_reverse = [];
+
+    /**
+     * Get the job with the given identifier.
+     *
+     * @param string $identifier Unique identifier of the job.
+     *
+     * @return BatchJob|null
+     */
+    public function getJobFromId($identifier)
+    {
+        return array_key_exists($identifier, $this->idmap)
+            ? $this->jobs[$identifier]
+            : null;
+    }
+
+    /**
+     * Get the job with the given numeric id.
+     *
+     * @param int $idNum A numeric id of the job.
+     *
+     * @return BatchJob|null
+     */
+    public function getJobFromIdNum($idNum)
+    {
+        return array_key_exists($idNum, $this->idmap_reverse)
+            ? $this->jobs[$this->idmap_reverse[$idNum]]
+            : null;
+    }
+
+    /**
+     * Register a job for executing in batch.
+     *
+     * @param string $identifier Unique identifier of the job.
+     * @param callable $func Any Callable except for Closure. The callable
+     *        should accept an array of items as the first argument.
+     * @param array $options [optional] {
+     *     Configuration options.
+     *
+     *     @type int $batchSize The size of the batch.
+     *     @type float $callPeriod The period in seconds from the last execution
+     *                 to force executing the job.
+     *     @type int $workerNum The number of child processes. It only takes
+     *               effect with the {@see \Google\Cloud\Core\BatchDaemon}.
+     *     @type string $bootstrapFile A file to load before executing the
+     *                  job. It's needed for registering global functions.
+     * }
+     * @return void
+     */
+    public function registerJob($identifier, $func, array $options = [])
+    {
+        if (array_key_exists($identifier, $this->idmap)) {
+            $idNum = $this->idmap[$identifier];
+        } else {
+            $idNum = count($this->idmap) + 1;
+            $this->idmap_reverse[$idNum] = $identifier;
+        }
+        $this->jobs[$identifier] = new BatchJob(
+            $identifier,
+            $func,
+            $idNum,
+            $options
+        );
+        $this->idmap[$identifier] = $idNum;
+    }
+
+    /**
+     * Get all the jobs.
+     *
+     * @return BatchJob[]
+     */
+    public function getJobs()
+    {
+        return $this->jobs;
+    }
+}