/ 
Myriad-1.000
River stage zero No dependents
/ Myriad::Guide::Tutorial

NAME

Myriad::Guide::Tutorial - introduction and tutorial for the Myriad framework

TUTORIAL

Most of the time, you would use the myriad.pl script to run everything.

The Myriad framework handles loading, logging, configuration and other tasks: you provide services which implement functionality, and wire them together. Instead of implementing top-level code, those services can call each other or subscribe to data streams.

Note that if you're on Windows, you may need to run the myriad.pl commands under PowerShell or WSL terminal, due to the nested quotes.

Run code on startup

Each service has a startup method - this is where you put code that should run once the service is loaded and ready.

package Myriad::Example::Startup;
# VERSION
# To try this out, run:
#  myriad.pl service Myriad::Example::Startup
use Myriad::Service ':v1';
async method startup (%args) {
 $log->infof('This is our example service, running code in the startup method');
}
1;

There are 3 key lines here - firstly, we give our service a name:

package Myriad::Example::Startup

Every service has a unique name, and we can have multiple instances of a given service (for example, connecting to different database shards or serving different domain names for a webhook).

Next, we load the framework and indicate that this is a service:

use Myriad::Service ':v1';

This line applies strict, warnings, and many other "standard" settings - see Myriad::Class for more details.

Next, we provide methods - in this case, a startup method:

async method startup (%args) {

We're using Object::Pad for the method keyword - every service is a Perl OO class, and Object::Pad is the prototype for the planned Perl core OO implementation. The async keyword comes from Future::AsyncAwait - it allows us to use the await keyword if there are any asynchronous operations that should complete before we return.

An RPC call

"Remote procedure calls", usually abbreviated RPC, are the basic building blocks for services. Creating a method marked as RPC tells Myriad that this method should be available for other services to call.

package Myriad::Example::RPC;
# VERSION
# To try this out, run:
#  myriad.pl service Myriad::Example::RPC rpc myriad.example.rpc
use Myriad::Service ':v1';
async method message : RPC {
 return 'Welcome to Myriad';
}
1;

We use subroutine attributes to mark a method as an RPC call.

Simple RPC echo method

This service takes parameters, in this case returning them as the result from the RPC call:

package Myriad::Example::Echo;
# VERSION
# To try this out, run:
#  myriad.pl service Myriad::Example::RPC rpc myriad.example.echo/message='{"message":"example message"}'
use Myriad::Service ':v1';
async method echo : RPC (%args) {
 return $args{message};
}
1;

We're using Perl core signatures for the parameters, although you can use @_ as usual if you prefer:

async method echo : RPC {
 my (%args) = @_;
 return $args{message};
}

Call another service

This service takes parameters, in this case returning them as the result from the RPC call:

package Myriad::Example::Call;
# VERSION
# To try this out, run:
#  myriad.pl service Myriad::Example::Call rpc myriad.example.call/remote_call
use Myriad::Service ':v1';
async method remote_call : RPC (%args) {
 my $srv = await $api->service_by_name('myriad.example.call');
 return await $srv->target_method;
}
async method target_method : RPC {
 return 'This is a method we call from within another service';
}
1;

The $api variable is available within services for accessing the service API - see Myriad::API for more details.