1#!/usr/bin/env python
2#
3# Copyright 2010 Google Inc.
4#
5# Licensed under the Apache License, Version 2.0 (the "License");
6# you may not use this file except in compliance with the License.
7# You may obtain a copy of the License at
8#
9#     http://www.apache.org/licenses/LICENSE-2.0
10#
11# Unless required by applicable law or agreed to in writing, software
12# distributed under the License is distributed on an "AS IS" BASIS,
13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14# See the License for the specific language governing permissions and
15# limitations under the License.
16
17"""API allowing control over some mapreduce implementation details."""
18
19
20
21__all__ = ["Hooks"]
22
23
24class Hooks(object):
25  """Allows subclasses to control some aspects of mapreduce execution.
26
27  control.start_map accepts an optional "hooks" argument that can be passed a
28  subclass of this class.
29  """
30
31  def __init__(self, mapreduce_spec):
32    """Initializes a Hooks class.
33
34    Args:
35      mapreduce_spec: The mapreduce.model.MapreduceSpec for the current
36        mapreduce.
37    """
38    self.mapreduce_spec = mapreduce_spec
39
40  def enqueue_worker_task(self, task, queue_name):
41    """Enqueues a worker task that is used to run the mapper.
42
43    Args:
44      task: A taskqueue.Task that must be queued in order for the mapreduce
45        mappers to be run. The task is named.
46      queue_name: The queue where the task should be run e.g. "default".
47
48    Raises:
49      NotImplementedError: to indicate that the default worker queueing strategy
50        should be used.
51    """
52    raise NotImplementedError()
53
54  def enqueue_kickoff_task(self, task, queue_name):
55    """Enqueues a task that is used to start the mapreduce.
56
57    This hook will be called within a transaction scope.
58    Hook should add task transactionally.
59
60    Args:
61      task: A taskqueue.Task that must be queued to run KickOffJobHandler.
62      queue_name: The queue where the task should be run e.g. "default".
63
64    Raises:
65      NotImplementedError: to indicate that the default mapreduce start strategy
66        should be used.
67    """
68    raise NotImplementedError()
69
70  def enqueue_done_task(self, task, queue_name):
71    """Enqueues a task that is triggered when the mapreduce completes.
72
73    This hook will be called within a transaction scope.
74    Hook should add task transactionally.
75
76    Args:
77      task: A taskqueue.Task that must be queued in order for the client to be
78        notified when the mapreduce is complete.
79      queue_name: The queue where the task should be run e.g. "default".
80
81    Raises:
82      NotImplementedError: to indicate that the default mapreduce notification
83        strategy should be used.
84    """
85    raise NotImplementedError()
86
87  def enqueue_controller_task(self, task, queue_name):
88    """Enqueues a task that is used to monitor the mapreduce process.
89
90    Args:
91      task: A taskqueue.Task that must be queued in order for updates to the
92        mapreduce process to be properly tracked. The task is named.
93      queue_name: The queue where the task should be run e.g. "default".
94
95    Raises:
96      NotImplementedError: to indicate that the default mapreduce tracking
97        strategy should be used.
98    """
99    raise NotImplementedError()
100