XS::Framework::Manual::recipe06 - XS::Framework advanced topic
Let's assume there is a different C++ libraries, offering similar capabilities, e.g. WAV-files playing library and multimedia-files (ogg, aac, mp3) playing library. Their interfaces are like:
/* is able to hold only files in WAV-format */ struct WAVFile { WAVFile(const char* name): name_{name} {} const char* name() const noexcept { return name_; } private: const char* name_; }; /* is able to hold any files only in ogg, mp3 and aac formats */ struct MultimediaFile { MultimediaFile(const char* name, const char* format): name_{name}, format_{format} {} const char* name() const noexcept { return name_; } const char* format() const noexcept { return format_; } private: const char* name_; const char* format_; }; struct WAVPlayer { WAVPlayer(double preferred_bitrate): preferred_bitrate_{preferred_bitrate} {} std::string play_wav(WAVFile* file) { std::string result = "wav-player is playing "; result += file->name(); result += " with bitrate "; result += std::to_string(preferred_bitrate_); return result; } double preferred_bitrate() const noexcept { return preferred_bitrate_; } WAVPlayer* clone() const noexcept { return new WAVPlayer(preferred_bitrate_); } private: double preferred_bitrate_; }; struct MultimediaPlayer { MultimediaPlayer(int quality): quality_{quality} {} std::string play_file(MultimediaFile* file) { std::string result = "player is playing "; result += file->name(); result += " ("; result += file->format(); result += ")"; result += " with quality "; result += std::to_string(quality_); return result; } int quality() const noexcept { return quality_; } MultimediaPlayer* clone() const noexcept { return new MultimediaPlayer(quality_); } private: int quality_; };
Their typemaps are trivial without inheritance and are omitted here (see t/cookbook/recipe08.xsi for full sources).
t/cookbook/recipe08.xsi
What we would like to achive is to "fix" C++ hierarchy in Perl: as WAVPlayer and MultimediaPlayer almost the same interface, and as MultimediaPlayer looks as the most generic one, let's have xs-adapter for MultimediaPlayer Perl, and let it inherits WAVPlayer xs-adapter, i.e. offers capabilities of the both C++ classes. (The xs-adapters for WAVFile and MultimediaFile are omitted)
WAVPlayer
MultimediaPlayer
WAVFile
MultimediaFile
MODULE = MyTest PACKAGE = MyTest::Cookbook::WAVPlayer PROTOTYPES: DISABLE std::string WAVPlayer::play_wav(WAVFile* file) double WAVPlayer::preferred_bitrate() WAVPlayer* WAVPlayer::new(double preferred_bitrate) # (1) WAVPlayer* WAVPlayer::clone() { // (2) Object self{ST(0)}; PROTO = self.stash(); // (3) RETVAL = THIS->clone(); // (4) }
The auto-generated constructor (1) will forward all provided parameters to the underlying C++ class; it is also aware of 1st argument CLASS/PROTO, i.e. SV* blessing will be performed into final class.
CLASS/PROTO
The clone (2) method performs acutally the same, hovewer we can't leave it as:
clone
WAVPlayer* WAVPlayer::clone()
because the PROTO hint will be empty, and by TypemapObject rules it will be blessed into TypemapObject::package, i.e. to MyTest::Cookbook::WAVPlayer, in other words it is not inheritance-aware. To fix that we have to manually write the clone method, which will forward to clone method of underlying C++ object (4) and bless it it to the actual Perl object package (3).
TypemapObject
TypemapObject::package
MyTest::Cookbook::WAVPlayer
Let's write xs-adapter for MultimediaPlayer, which fixes C++ class hierarchy:
MODULE = MyTest PACKAGE = MyTest::Cookbook::MultimediaPlayer PROTOTYPES: DISABLE MultimediaPlayer* MultimediaPlayer::new(double preferred_bitrate, int quality) { (void)preferred_bitrate; // silence warning PROTO = Stash::from_name(CLASS).call_next(cv, &ST(1), 1); // (5) if (!PROTO.defined()) XSRETURN_UNDEF; RETVAL = new MultimediaPlayer(quality); // (6) } std::string MultimediaPlayer::play_file(MultimediaFile* file) int MultimediaPlayer::quality() MultimediaPlayer* MultimediaPlayer::clone() { Object self{ST(0)}; PROTO = self.call_next(cv); // (7) RETVAL = THIS->clone(); // (8) } BOOT { auto stash = Stash(__PACKAGE__, GV_ADD); stash.inherit("MyTest::Cookbook::WAVPlayer"); // (9) }
First, in the constructor new the base SV* wrapper have to be created in (5). It actually forwards call to the new method of WAVPlayer xs-adapter (1). Then it creates MultimediaPlayer C++ object in (6) and, as the PROTO variable already contains SV* wrapper, by XS::Framework rules the MultimediaPlayer C++ object will attached to SV*. Please, note that SV* wrapper will be already blessed into the right package after (5).
new
PROTO
The clone method (7)..(8) is similar to the new constructor, i.e. it first clones (7) XS-adapter for WAVPlayer (which clones C++ class WAVPlayer), and after (8) the pointer to C++ MultimediaPlayer object will be attached to it. Please, note, that THIS variable is C++ MultimediaPlayer at line (8), and it is WAVPlayer at line (4).
THIS
It should be noted, that in (5) and (7) the call_next is used. It could be changed to call_SUPER, but call_next is somewhat more general.
call_next
call_SUPER
In the line (9) we should specify that MultimediaPlayer xs-adapter inherits from WAVPlayer adapter. The following test proves correctness:
my $wav = MyTest::Cookbook::WAVFile->new('sample.wav'); my $ogg = MyTest::Cookbook::MultimediaFile->new('sample.ogg', 'ogg'); my $player = MyTest::Cookbook::MultimediaPlayer->new(44100, 6); my $clone = $player->clone; is $clone->quality, 6; is $clone->preferred_bitrate, 44100; is $clone->play_file($ogg), 'player is playing sample.ogg (ogg) with quality 6'; is $clone->play_wav($wav), 'wav-player is playing sample.wav with bitrate 44100.000000';
The short summary: if needed it is possible to fix/enrich C++ class hierarchry in Perl classes (xs-adapters).
To install XS::Framework, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XS::Framework
CPAN shell
perl -MCPAN -e shell install XS::Framework
For more information on module installation, please visit the detailed CPAN module installation guide.