There is an ongoing outage on the primary CPAN mirror. It is possible to work around the issue by using MetaCPAN as a mirror.

 / 
Schedule-Activity-0.1.0
/ Schedule::Activity

NAME

Schedule::Activity - Generate random activity schedules

VERSION

Version 0.1.0

SYNOPSIS

use Schedule::Activity;
my %schedule=Schedule::Activity::buildSchedule(
  configuration=>{
    node=>{
      Activity=>{
        message=>'Begin Activity',
        next=>['action 1'],
        tmmin=>5,tmavg=>5,tmmax=>5,
        finish=>'Activity, conclude',
      },
      'action 1'=>{
        message=>'Begin action 1',
        tmmin=>5,tmavg=>10,tmmax=>15,
        next=>['action 2'],
      },
      'action 2'=>{
        message=>'Begin action 2',
        tmmin=>5,tmavg=>10,tmmax=>15,
        next=>['Activity, conclude'],
      },
      'Activity, conclude'=>{
        message=>'Conclude Activity',
        tmmin=>5,tmavg=>5,tmmax=>5,
      },
    },
  },
  activities=>[
    [30,'Activity'],
  ],
);
print join("\n",map {"$$_[0]:  $$_[1]{message}"} @{$schedule{activities}});

DESCRIPTION

EXPERIMENTAL: This module is currently experimental and subject to change. Core functionality is safe for use in this version, but there are still some exceptional cases that may die(); callers should plan to trap and handle these exceptions accordingly. Documentation per option below may note other areas subject to change.

This module permits building schedules of activities each containing randomly-generated lists of actions. This two-level approach uses explicit goal times to construct the specified list of activities. Within activities, actions are chosen within configured limits, possibly with randomization and cycling, using slack and buffer timing adjustments to achieve the goal.

For additional examples, see the samples/ directory.

CONFIGURATION

A configuration for scheduling contains the following sections:

%configuration=(
  node=>{...}
  message  =>... # not yet supported
  insertion=>... # not yet supported
)

Both activities and actions are configured as named node entries. With this structure, an action and activity can share a message, but must use different key names.

'activity name'=>{
  message=>... # an optional message string or object
  next=>[...], # list of child node names
  finish=>'activity conclusion',
  (time specification)
}
'action name'=>{
  message=>... # an optional message string or object
  next=>[...], # list of child node names
  (time specification)
}

The list of next nodes is a list of names, which must be defined in the configuration. During schedule construction, entries will be chosen randomly from the list of next nodes. The conclusion must be reachable from the initial activity, or scheduling will fail. There is no further restriction on the items in next: Scheduling specifically supports cyclic/recursive actions, including self-cycles.

There is no functional difference between activities and actions, except that a node must contain finish to be used for activity scheduling. Nomenclature is primarily to support schedule organization: A collection of random actions is used to build an activity; a sequence of activities is used to build a schedule.

Time specification

The only time specification currently supported is:

tmmin=>seconds, tmavg=>seconds, tmmax=>seconds

Values must be non-negative numbers. All three values may be identical. Note that scheduling to a given goal may be impossible without slack or buffer within some of the actions:

slack =tmavg-tmmin
buffer=tmmax-tmavg

The slack is the amount of time that could be reduced in an action before it would need to be removed/replaced in the schedule. The buffer is the amount of time that could be added to an action before additional actions would be needed in the schedule.

Future changes may support abbreviated time specifications, automatic slack/buffering, univeral slack/buffer ratios, and open-ended/relaxed slack/buffering.

Messages

Each activity/action node may contain an optional message string. Nothing in the scheduler uses these messages; they are provided so the caller can easily handle the returned schedules.

Future changes may support an array of messages, with each entry being a string or object. This would support configured random message selection. A message hash may also be supported. One proposal links the string in the message, to the collection of top-level configuration{message} keys; while this structure has not been fully defined, carefully choose message strings that are unlikely to clash with potential future keynames.

RESPONSE

The response from buildConfig is:

%schedule=(
  error=>['list of validation errors, if any',...],
  activities=>[
    seconds, message],
    ..,
  ],
)

Failures

In addition to validation failures returned through error, the following may cause the scheduler to die(): The activity name is undefined. The scheduler was not able to reach the named finish node. The number of retries or backtracking attempts has been exhausted.

The difference between the result time and the goal may cause retries when an excess exceeds the available slack, or when a shortage exceeds the available buffer.

Caution: While startup/conclusion of activities may have fixed time specifications, at this time it is recommended that actions always contain some slack/buffer. There is currently no "relaxing mechanism" during scheduling, so a configured with no slack nor buffer must exactly meet the goal time requested.

SEE ALSO

Schedule::LongSteps and Chronic address the same type of schedules with slightly different goals.