Bitflu internals - adrian-bl/bitflu GitHub Wiki

Bitflu was written in perl, so if you'd like to contribute any code you should be able to write clean perl code ;-)

Keep in mind that bitflu is somewhat like a small operating system: It has a primitive scheduler/dispatcher, offers Networking service and does all IO for you (So your perl code will NEVER call open())

Table of Contents How to write a plugin Using the Configuration service How to do networking How to call the storage plugin How to create SxTasks

How to write a plugin

I'd recommend to look at some 'easy' plugin such as Cron.pm.

Your plugin will need a line that says

 use constant _BITFLU_APIVERSION  => CURRENT_API_VERSION;

This will let bitflu know that this plugin was built for the currently running version in mind. Bitflu will refuse to load plugins with an invalid APIVERSION.

You also need a 'register' routine: Bitflu will call this sub after your plugin has been loaded. The register subroutine should return a blessed reference to itself and might call $mainclass->AddRunner($self) if it would like to get called by bitflus dispatcher.

 sub register {
   my($class,$mainclass) = @_;
   my $self = { super=>$mainclass };
   bless($self,$class);
   $mainclass->AddRunner($self);
   return $self;
 }

Bitflu also expects an init subroutine. This sub just needs to return 'true' and is called after all plugins have been loaded:

 sub init {
  return 1;
 }

If your plugin called ->AddRunner you must also have a 'run' subroutine: This sub will get called each X seconds by bitflus scheduler:

 sub run {
  my($self, $NOWTIME) = @_;
  $self->{super}->warn("Got called at $NOWTIME !");
  return 4;
 }

Note the 'return 4': This will instruct the scheduler to call ->run each ~4 seconds

Using the Configuration service

Bitflu provides a builtin configuration plugin that you can use via $super->Configuration

Use $super->Configuration->GetValue('keyname') to read data from the configuration. It will return undef if the value is not set.

Use $super->Configuration->GetValue('keyname',$val); to set a config key. Returns true on success and false otherwise (eg. the value was locked)

You can also lock a value for runtime configuration. This can be used for values that must not be changed while running (eg. torrent_bind, torrent_port)

Use $super->Configuration->RuntimeLockValue('keyname') to lock it and $super->Configuration->IsRuntimeLocked('keyname') to check if a value is locked. Locking a value cannot be undone!

How to do networking

todo

How to call the storage plugin

todo

How to create SxTasks

An SxTask (Simple-eXecutation-Task) is sort of a mini-plugin/thread. Creating a new SxTask is pretty simple:

 my $sxt = $self->{super}->CreateSxTask(Superclass=>$self,Callback=>'DoSomething', Args=>[5]);

This will instruct bitflus scheduler to call $self->DoSomething(5) just like it calls the ->run subroutine. ('DoSomething' will also be able to use a return value to define how long the scheduler should wait before calling it again)

To stop/destroy an SxTask the DoSomething sub must return 0. You can also call

 $sxt->destroy;

to kill the SxTask. Please note that ->destroy does not do any cleanups. Bad things will happen if you destroy an SxTask with open Networking handles.

(This might change in future but for now there is no cleanup done by bitflu. It will just crash and burn :-) )