.. _tutorial: ******** Tutorial ******** This tutorial gives a step by step narrative for creating an example application. The application built throughout this section is a pi calculator that uses the dartboard algorithm. Overview ======== * :ref:`Creating a Task Class` * :ref:`Connect to the job scheduler` * :ref:`Submit Job` * :ref:`Waiting for task results` * :ref:`The complete application` * :ref:`Next Steps` Creating a Task Class ===================== The very first step is defining a task. A task represents the code that will run. The most important aspect of writing a task class is implementing the :py:meth:`execute` method. This :py:meth:`execute` method is the entry point into the Task. For this pi calculator, the :py:meth:`execute` method of the task contains the logic of the dartboard algorithm. Here is the code: .. literalinclude:: .\..\..\code\ProgrammersGuide\DartboardExample.py :language: python :linenos: :lines: 5-18 Connect to the Job Scheduler ============================ Connecting to the Coordinator consists of one line. The hostname is the DNS name or IP address of the Coordinator. If the coordinator is not running on the default port (9090), also specify the port number. The :py:meth:`connect() ` method must be called before any of the operations on the coordinator can be performed. Once Connect is successfully called, call :py:func:`disconnect() ` on the client when it is no longer needed. Otherwise, unnecessary coordinator resources will be consumed and the application may not exit properly. Alternatively, declare and instantiate the job scheduler within a :py:obj:`with` statement to ensure it is properly disconnected. .. literalinclude:: .\..\..\code\ProgrammersGuide\DartboardExample.py :language: python :linenos: :dedent: 4 :lines: 22-23 .. note:: If an exception is thrown at the Connect method and says something like "Cannot connect to Coordinator", the most likely reason is that the Coordinator is not running on the specified machine and port. Make sure coordinator is running on that machine and confirm a firewall is not blocking the port. .. image:: ..\\..\\..\\..\\..\\Documentation\\Media\\ClusterConnectException.png :align: center :alt: ClusterConnectException Submit Job ========== After connecting to the coordinator, specify tasks to submit. First, create a :py:class:`Job ` using :py:func:`create_job() `. Next, instantiate the Task(s) written :ref:`above `. For the pi calculator, add multiple tasks to the job to get more samples. When finished adding tasks, the :py:meth:`submit() ` method will actually submit the job to the coordinator. .. note:: The are also many options on the job that you could specify. For this tutorial, you will just use two of the options, :py:attr:`name ` and :py:attr:`description `. The pi calculator submit code should look like this: .. literalinclude:: .\..\..\code\ProgrammersGuide\DartboardExample.py :language: python :linenos: :dedent: 8 :lines: 25-32 Waiting for Task Results ======================== Calling :py:meth:`wait_until_done() ` will block the current thread until all of the job's tasks are completed. Once the job is completed, the result of each task is sent back to the client. One of the results you can get from the task is from the :py:attr:`result` property. For the pi calculator, you want to sum up the task's result. The wait_until_done code will look like this: .. literalinclude:: .\..\..\code\ProgrammersGuide\DartboardExample.py :language: python :linenos: :dedent: 8 :lines: 33-41 The Complete Application ======================== Here is the complete application after all the steps are applied: .. literalinclude:: .\..\..\code\ProgrammersGuide\DartboardExample.py :language: python :linenos: Next Steps ========== With an example application completed, explore other concepts at :ref:`keyconcepts` or review the :ref:`Library Reference `. See Also ======== Reference """"""""" * :py:class:`Job `