@dontirun/state-machine-semaphore

An aws-cdk construct that enables you to use AWS Step Functions to control concurrency in your distributed system. You can use this construct to distributed state machine semaphores to control concurrent invocations of contentious work.

This construct is based off of Justin Callison's example code. Make sure to check out Justin's blogpost to learn about how the system works.

Examples

Example 1) A state machine with a controlled job

Click to see code

import { Function } from 'aws-cdk-lib/aws-lambda';
import { Duration, Stack, StackProps } from 'aws-cdk-lib';
import { StateMachine, Succeed, Wait, WaitTime } from 'aws-cdk-lib/aws-stepfunctions';
import { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';
import { Construct } from 'constructs';
import { Semaphore } from '@dontirun/state-machine-semaphore';


export class CdkTestStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const contestedJob = new LambdaInvoke(this, 'ContestedJobPart1', {
      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart1', 'cool-function'),
    }).next(new Wait(this, 'Wait', { time: WaitTime.duration(Duration.seconds(7)) }))
      .next(new Wait(this, 'AnotherWait', { time: WaitTime.duration(Duration.seconds(7)) }))
      .next(new Wait(this, 'YetAnotherWait', { time: WaitTime.duration(Duration.seconds(7)) }));

    const afterContestedJob = new Succeed(this, 'Succeed');

    const stateMachineFragment = new Semaphore(stack, 'Semaphore', { lockName: 'life', limit: 42, job: contestedJob, nextState: afterContestedJob });

    new StateMachine(this, 'StateMachine', {
      definition: stateMachineFragment,
    });
  }
}

Click to see the state machine definition

Example 1 Definition

Example 2) A state machine with multiple semaphores

Click to see code

import { Function } from 'aws-cdk-lib/aws-lambda';
import { Duration, Stack, StackProps } from 'aws-cdk-lib';
import { StateMachine, Succeed, Wait, WaitTime } from 'aws-cdk-lib/aws-stepfunctions';
import { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';
import { Construct } from 'constructs';
import { Semaphore } from '@dontirun/state-machine-semaphore';


export class CdkTestStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const contestedJob = new LambdaInvoke(this, 'ContestedJobPart1', {
      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart1', 'cool-function'),
    })
    const notContestedJob = new LambdaInvoke(this, 'NotContestedJob', {
      lambdaFunction: Function.fromFunctionName(this, 'NotContestedJobFunction', 'cooler-function'),
    })
    const contestedJob2 = new LambdaInvoke(this, 'ContestedJobPart2', {
      lambdaFunction: Function.fromFunctionName(this, 'JobFunctionPart2', 'coolest-function'),
    })
    const afterContestedJob2 = new Succeed(this, 'Succeed');

    const definition = new Semaphore(stack, 'Semaphore', { lockName: 'life', limit: 42, job: contestedJob, nextState: notContestedJob })
      .next(new Semaphore(stack, 'Semaphore2', { lockName: 'liberty', limit: 7, job: contestedJob2, nextState: afterContestedJob2 }));

    new StateMachine(this, 'StateMachine', {
      definition: definition,
    });
  }
}

Click to see the state machine definition

Example 2 Definition

API Reference

See API.md.

License

This project is licensed under the Apache-2.0 License.

Release files for state-machine-semaphore 0.1.583

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for state-machine-semaphore 0.1.583
File	Size	Uploaded
state-machine-semaphore-0.1.583.tar.gz	331.7 kB	Apr 28, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for state-machine-semaphore 0.1.583
File	Interpreter	ABI	Platform	Reset
state_machine_semaphore-0.1.583-py3-none-any.whl 329.9 kB Apr 28, 2024	Python 3	none	any	Details

Total release size: 661.6 kB

Release files / state-machine-semaphore-0.1.583.tar.gz

Download URL	state-machine-semaphore-0.1.583.tar.gz
Size	331.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`93cbd0c91b52e75a3728b45eac4c6c447dd68aefaed832b79988c7e58d1b5888`
BLAKE2b-256 checksum How to use checksums	`f46740a819325408612d484771aec124467f2c8f4781618f1b22effe2e1e559c`
Upload date	Apr 28, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.12.3`

Release files / state_machine_semaphore-0.1.583-py3-none-any.whl

Download URL	state_machine_semaphore-0.1.583-py3-none-any.whl
Size	329.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a88d7fe4ad8f2659dc18158b6f3bd7d42a49c9a7762c3198606ec69fef35d412`
BLAKE2b-256 checksum How to use checksums	`86a09f336706219abb4f3851a75d9eedcd9841fdcd8d4af1ff5fc4c263df8235`
Upload date	Apr 28, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.12.3`