go.uber.org/cadence@v1.2.9/cadence.go (about)

     1  // Copyright (c) 2017 Uber Technologies, Inc.
     2  //
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  //
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  //
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  /*
    22  Package cadence and its subdirectories contain the Cadence client side framework.
    23  
    24  The Cadence service is a task orchestrator for your application’s tasks. Applications using Cadence can execute a
    25  logical flow of tasks, especially long-running business logic, asynchronously or synchronously. They can also scale at
    26  runtime on distributed systems.
    27  
    28  A quick example illustrates its use case. Consider Uber Eats where Cadence manages the entire business flow from
    29  placing an order, accepting it, handling shopping cart processes (adding, updating, and calculating cart items),
    30  entering the order in a pipeline (for preparing food and coordinating delivery), to scheduling delivery as well as
    31  handling payments.
    32  
    33  Cadence consists of a programming framework (or client library) and a managed service (or backend). The framework
    34  enables developers to author and coordinate tasks in Go code.
    35  
    36  The root cadence package contains common data structures. The subpackages are:
    37  
    38    - workflow - functions used to implement workflows
    39    - activity - functions used to implement activities
    40    - client - functions used to create Cadence service client used to start and
    41      monitor workflow executions.
    42    - worker - functions used to create worker instance used to host workflow and
    43      activity code.
    44    - testsuite - unit testing framework for activity and workflow testing
    45  
    46  # How Cadence works
    47  
    48  The Cadence hosted service brokers and persists events generated during workflow execution. Worker nodes owned and
    49  operated by customers execute the coordination and task logic. To facilitate the implementation of worker nodes Cadence
    50  provides a client-side library for the Go language.
    51  
    52  In Cadence, you can code the logical flow of events separately as a workflow and code business logic as activities. The
    53  workflow identifies the activities and sequences them, while an activity executes the logic.
    54  
    55  # Key Features
    56  
    57  Dynamic workflow execution graphs - Determine the workflow execution graphs at runtime based on the data you are
    58  processing. Cadence does not pre-compute the execution graphs at compile time or at workflow start time. Therefore, you
    59  have the ability to write workflows that can dynamically adjust to the amount of data they are processing. If you need
    60  to trigger 10 instances of an activity to efficiently process all the data in one run, but only 3 for a subsequent run,
    61  you can do that.
    62  
    63  Child Workflows - Orchestrate the execution of a workflow from within another workflow. Cadence will return the results
    64  of the child workflow execution to the parent workflow upon completion of the child workflow. No polling is required in
    65  the parent workflow to monitor status of the child workflow, making the process efficient and fault tolerant.
    66  
    67  Durable Timers - Implement delayed execution of tasks in your workflows that are robust to worker failures. Cadence
    68  provides two easy to use APIs, **workflow.Sleep** and **workflow.Timer**, for implementing time based events in your
    69  workflows. Cadence ensures that the timer settings are persisted and the events are generated even if workers executing
    70  the workflow crash.
    71  
    72  Signals - Modify/influence the execution path of a running workflow by pushing additional data directly to the workflow
    73  using a signal. Via the Signal facility, Cadence provides a mechanism to consume external events directly in workflow
    74  code.
    75  
    76  Task routing - Efficiently process large amounts of data using a Cadence workflow, by caching the data locally on a
    77  worker and executing all activities meant to process that data on that same worker. Cadence enables you to choose the
    78  worker you want to execute a certain activity by scheduling that activity execution in the worker's specific task-list.
    79  
    80  Unique workflow ID enforcement - Use business entity IDs for your workflows and let Cadence ensure that only one
    81  workflow is running for a particular entity at a time. Cadence implements an atomic "uniqueness check" and ensures that
    82  no race conditions are possible that would result in multiple workflow executions for the same workflow ID. Therefore,
    83  you can implement your code to attempt to start a workflow without checking if the ID is already in use, even in the
    84  cases where only one active execution per workflow ID is desired.
    85  
    86  Perpetual/ContinueAsNew workflows - Run periodic tasks as a single perpetually running workflow. With the
    87  "ContinueAsNew" facility, Cadence allows you to leverage the "unique workflow ID enforcement" feature for periodic
    88  workflows. Cadence will complete the current execution and start the new execution atomically, ensuring you get to
    89  keep your workflow ID. By starting a new execution Cadence also ensures that workflow execution history does not grow
    90  indefinitely for perpetual workflows.
    91  
    92  At-most once activity execution - Execute non-idempotent activities as part of your workflows. Cadence will not
    93  automatically retry activities on failure. For every activity execution Cadence will return a success result, a failure
    94  result, or a timeout to the workflow code and let the workflow code determine how each one of those result types should
    95  be handled.
    96  
    97  Asynch Activity Completion - Incorporate human input or thrid-party service asynchronous callbacks into your workflows.
    98  Cadence allows a workflow to pause execution on an activity and wait for an external actor to resume it with a
    99  callback. During this pause the activity does not have any actively executing code, such as a polling loop, and is
   100  merely an entry in the Cadence datastore. Therefore, the workflow is unaffected by any worker failures happening over
   101  the duration of the pause.
   102  
   103  Activity Heartbeating - Detect unexpected failures/crashes and track progress in long running activities early. By
   104  configuring your activity to report progress periodically to the Cadence server, you can detect a crash that occurs 10
   105  minutes into an hour-long activity execution much sooner, instead of waiting for the 60-minute execution timeout. The
   106  recorded progress before the crash gives you sufficient information to determine whether to restart the activity from
   107  the beginning or resume it from the point of failure.
   108  
   109  Timeouts for activities and workflow executions - Protect against stuck and unresponsive activities and workflows with
   110  appropriate timeout values. Cadence requires that timeout values are provided for every activity or workflow
   111  invocation. There is no upper bound on the timeout values, so you can set timeouts that span days, weeks, or even
   112  months.
   113  
   114  Visibility - Get a list of all your active and/or completed workflow. Explore the execution history of a particular
   115  workflow execution. Cadence provides a set of visibility APIs that allow you, the workflow owner, to monitor past and
   116  current workflow executions.
   117  
   118  Debuggability - Replay any workflow execution history locally under a debugger. The Cadence client library provides an
   119  API to allow you to capture a stack trace from any failed workflow execution history.
   120  */
   121  package cadence
   122  
   123  import "go.uber.org/cadence/internal"
   124  
   125  // RetryPolicy defines the retry policy for activity/workflow.
   126  type RetryPolicy = internal.RetryPolicy