2010Q3 Grant Proposal: Improve Parrot Embed/Extend Subsystem Tests and Documentation


Improve Parrot Embed/Extend Subsystem Tests and Documentation


Jonathan "Duke" Leto.


[hidden email]

Amount Requested:



Currently the Parrot [0] Embedding subsystem is under-tested and under-documented. This grant proposes to add documentation for all public Embed/Extend API functions, write tests to increase the code coverage statistics for the Embed/Extend API to at least 95%, and update the Parrot Developer Docs (PDDs) [1] where errors or omissions are found. Any bugs found on the way that cannot be easily fixed will be reported on the Parrot Trac bug-tracker with test cases.

Benefits to the Perl Community

There are many projects that will benefit from a completely documentated and thoroughly tested Parrot Embed Subsystem. Rakudo Perl 6 [2] is built on Parrot, so people who want to embed Rakudo Perl 6 in any other application will benefit. Blizkost is a bridge between Perl 5 and Parrot, and embeds both, so will greatly benefit from good documentation and tests. PL/Parrot [3] is a project that aims to embed Parrot in the PostgreSQL database [4]. Because Parrot is embedded in PostgreSQL, any language that runs on Parrot then can easily be embedded. PL/Perl6 is part of the PL/Parrot project, which loads Rakudo Perl 6 bytecode and therefore embeds a Perl 6 interpreter inside of PostgreSQL, for use in writed stored procedures. All of these projects will grealy benefit from complete documentation, as well any any future applications that want to embed or extend Parrot.


According to the code coverage stats [5] for Embed Extend API in Parrot Subversion revision 48100, the code coverage of src/embed.c is 65.2%, src/extend.c is 71.2% and src/extend_vtable.c is 5.3%. All of these will be raised to at least 95% by writing the appropriate tests.

The embed API documentation in docs/embed.pod [6] contains many parts which are missing documentation, such as the "Lexicals", "Type Signatures" and "Constants" sections. This will be filled with the appropriate documenation as it works currently.

A blog post will also be made on a blog syndicated by Perlsphere, describing how the grant proceeded, lessons learned, bugs found, a summary of tests written and links to the new documentation.

Project Details

Currently only about 5 of over 180 functions in src/extend_vtable.c have test coverage. This will likely require around 50 tests fully cover each function, but this number can vary depending on the size of a test. The majority of these tests are simply calling a variety of VTABLE functions on PMCs, so each test has roughly the same structure. These tests will be added to t/src/extend_vtable.t (a new test file) and written in Perl 5.

The test coverage for src/embed.c and src/extend.c is much higher, so fewer tests will be required, but these tests will be more complicated due to the necessity of testing corner cases. Much of the uncovered code in src/embed.c relates to dealing packfiles and bytecode, error handling with I/O and using non-default runcores. These tests will be added to t/src/embed.t and t/src/extend.t, respectively, and written in Perl 5.

The documentation part of this grant should be straight-forward, but anything that needs to be clarified will be put to the parrot-dev mailing list.


The first inch-stone will be updating docs/embed.pod to contain the "Lexicals", "Type Signatures" and "Constants" sections. This should take one to two weeks.

The next two inch-stones will be to raise extend_vtable.c to 50% and then 95% coverage. This splits the work roughly in half, and I expect each to take roughly 2 weeks.

The tests for embed.c are fewer but will be trickier, so I expect to have two inch-stones, one for 80% coverage and the other for 95% coverage, and I expect each to take about 2-3 weeks.

The last inch-stone will be the easiest: writing and publishing the blog post. I expect this to take about a day.

Project Schedule

I expect to be able to work about 5-10 hours per week, starting in October, so it does not conflict with Google Summer of Code. I expect that at this pace, this grant will take about 2-3 months to finish, taking into account that I may not work as much around the holidays.

Completeness Criteria

Since this work will not change any features, it can be committed directly to Parrot SVN trunk incrementally. When the code coverage statistics have all reached >= 95%, the missing sections of documentation have been written and the blog post has been published, this grant will be considered complete.


I've hacked on Parrot Virtual Machine ever since I attended a Parrot Hackathon in 2008. I started off hacking on the Perl 6 test suite, after getting a commit bit from Larry at the hackathon due to my interest in fixing some bugs and adding tests relating to math functions and complex numbers. This quickly led me to bugs in Parrot, and I have mostly been writing tests and fixing bugs for the Parrot test suite ever since. I have converted large partions of the test suite from Perl 5 to PIR, as well as implementing parts of Test::More and a TAP Parser in PIR. I am also the organization administrator for The Perl Foundation/Parrot Foundation in Google Summer of Code 2010, as well as a mentor for Parrot on RTEMS [7].

I also hack on a project called PL/Parrot, which embeds Parrot and Rakudo Perl 6 into the PostgreSQL database. It is one of the first projects to embed Parrot in other applications, the others being mod_parrot and Blizkost. I believe it is the first project to embed Rakudo Perl 6. In the course of hacking on PL/Parrot, I have written tests for the Parrot embedd/extend API and fixed documentation, as well as contributing patches and tests for Rakudo.

Since I am a Parrot Core Developer, I can commit directly to Parrot trunk, which is the best scenario, since everyone will benefit incrementally from better code coverage and documentation.

As for other credentials, I have a Masters in Mathematics from University of Central Florida and have published various papers on differential equations, as well as being a coauthor of the Google Summer of Code Mentor Manual [8].


[0] http://parrot.org

[1] http://docs.parrot.org/parrot/latest/html/pdds.html

[2] http://rakudo.org

[3] http://pl.parrot.org

[4] http://postgresql.org

[5] http://tapir2.ro.vutbr.cz/cover/cover-results/

[6] http://docs.parrot.org/parrot/devel/html/docs/embed.pod.html

[7] http://rtems.org

[8] http://en.flossmanuals.net/GSoCMentoringGuide


I'm not familiar with the Parrot documentation and test suite, but this sounds like a good idea. One of the really strong points that the Perl community has right now is the prevalence of testing that we've developed over the years. It would be good to continue this.

I'd certainly like to see this work done.

I'd just add that it would be good to have a discussion to review the current API design before it gets 'pinned down' by docs and tests. That could be done while waiting for grant approval.

I'm in favor of any attempt to improve existing Parrot documentation. My question is sort of vague and hand-wavey. Sorry about that.

I respect the desire to wait for the dust to settle on the current API design. At the same time, an API design review could take a while and documentation is needed soon. If you implemented the documentation now, how could you minimize the impact of underlying code changes on your work?

Tim: Thanks for your encouragement. I have sent this proposal to parrot-dev and will ask if any changes in the current API design are planned.

The latest version of this proposal can be found at:


About TPF

The Perl Foundation - supporting the Perl community since 2000. Find out more at www.perlfoundation.org.

About this Entry

This page contains a single entry by Alberto Simões published on August 1, 2010 3:09 PM.

2010Q3 Grant Proposal: CPAN to deb autopackaging was the previous entry in this blog.

2010Q3 Grant Proposal: YAC (YACCMS (Yet Another Catalyst CMS))) is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.


OpenID accepted here Learn more about OpenID
Powered by Movable Type 6.2.2