glibc -- ISO C11 threads Proposal

[Kevin Cox <kevincox at kevincox dot ca>]

Hello,

I think that adding C11 thread support would be an excellent feature to
have in glibc.  I have attached a draft of my GSOC proposal below and
would appreciate feedback (both positive and negative).

I am proposing that C11 threads should be implemented on top of pthreads
as suggested on the ideas page.  Not only will the reduce maintenance
burden and bug/attack surface but it also allows different programs and
libraries to interoperate through the extension functions I have
proposed that allow conversion from C11 to posix.

Cheers,
Kevin




Personal Info
-------------
name:    Kevin Cox
email:   kevincox@kevincox.ca
xmpp:    kevincox@kevincox.ca
irc:     kevincox
phone:   <omitted>
pgp key: E394 3366 624E 7449 B9B4 85AE C075 8A3B 34D5 2E74

Project Info
------------
Project name: glibc -- ISO C11 threads

Summary
-------

The goal of this project is to implement the threading functions from
ISO C11 in the GNU C Library.  This includes the new header file
`threads.h` and the backing code to implement the functions defined in
that header using the already present pthread implementation.  This
project will also create the matching tests to ensure that the
implementation is correct and documentation so that users know how to
use the new API.

Benefits
--------
These functions provide standard utilities for threading in the C
language.  This enables authors to create programs that will run across
any standard C11 implementation.

This work will add support for this part of the standard making the GNU
C Library better featured and a more attractive option for developers.

Deliverables
------------

A standards compliant (with the exception of extensions added)
implementation of the `threads.h` header described in the ISO C11
Standard.  All of the macros, types, constants and functions defined in
section "7.26 Threads <threads.h>" of the standard will be available
with the following additions (which may be renamed) which will be
defined if _GNU_SOURCE is defined (this may be discussed and changed).

/* Get the pthread_t corresponding to the passed in thread */
pthread_t
thrd_pthread(thrd_t thrd);

/* Get the pthread_mutex_t corresponding to the passed in mutex */
pthread_mutex_t *
mtx_pthread(mtx_t *mtx);

/* Get the pthread_cond_t corresponding to the passed in condition
   variable */
pthread_cond_t *
cnd_pthread(cnd_t &thrd);

The associated documentation for the macros, constants and functions
defined in threads.h will be created.

Tests will be added to ensure correctness of the implementation.

Throughout the project a public git repository will be regularly updated
with my development progress.

Plan
----

I have no other plans over the summer so I can easily dedicate 40 hours
a week to this project and can allocate more time if necessary.

The implementation will take place based on dependence and importance.
I want to establish meaningful test cases as quickly as possible so that
most of the work will be driven by tests.  This will reduce the overall
time requirement as bug-hunting will be lower.  In order to do this I
plan to implement the library in this order.

0: Implement macros, constants and typedefs so that functions can be
   defined.  This also involves resolving namespacing issues such as
   renaming some of the pthread functions and providing aliases.

First the threading functions are enabled.  It is near impossible to
test the mutex and condition variable function without multiple threads.

1: thrd_create and thrd_join.  This should allow to spawn a thread and
   test that it has been spawned.
2: thrd_equal.  Test that same threads are equal.
3: thrd_current. Test that a thread identifier can be retrieved.
4: thrd_exit, thrd_join and thrd_detach.
5: thrd_sleep, thrd_yield: thrd_yeild doesn't have to do anything, so
   testing will be hard.

Secondly the mutex functions will be implemented as the condition
variables rely on them.

6: mtx_init, mtx_destroy, mtx_lock and mtx-unlock.  This should allow
   for working tests.
7: mtx_recursive support.
8: mtx_trylock, mtx_timedlock.

Next condition variables will be implemented.

7: cnd_init, cnd_destroy, cnd_wait, cnd_signal.  Basic condition 	
   variable routines.
8: cnd_broadcast, cnd_timedwait. Rest of the API.

Finally the odds and ends will be implemented.

9: call_once, tss_create, tss_delete, tss_set, tss_get.
10: thrd_pthread, mtx_pthread, cnd_pthread.

11: Overarching documentation.

Timeline
--------

Over the three month period I will use my time as follows.  Note that if
for some reason I fall behind finishing the earlier items is of a higher
priority then starting new work items.  This will ensure that even if I
fall behind the amount that is implemented is well done and able to be
picked up (by me) after the summer is over.

May 1-18:
  Re-read documentation on both GNU C Library and the C11 standard.
  Especially important in this time is identifying the pthread
  functions that will be required and renaming them if necessary to
  avoid namespacing issues.  It is likely that an initial patch
  renaming the affected functions will be created to get that issue out
  of the way.

May 19 - June 8:
  Implement steps 0-5.  This includes basic definitions and full
  threading support.  As well as the code implementation the build
  system will be modified to build it and run the newly created tests.
June 9-22:
  Documentation time, clean up and buffer.  During this time reference
  documentation for the newly implemented threading functions will be
  added and the code will be cleaned up (style guidelines and general
  tidiness).  Also, if the threading implementation is not complete
  this time will be used as a buffer in which to catch up.  If all is
  complete work can advance ahead of schedule.

June 22:
  Mid-term review.  By this time all of the required symbols should be
  exported from the threads.h header file and implementations for all
  of the thrd_* (except the proposed thrd_pthread function) should be
  working.  They should also have tests and supporting documentation.

June 23 - July 7:
  Implement steps 6-8.  This includes all mtx_* functions and the
  associated tests.  Furthermore reference documentation for these
  functions will be written.
July 8-20:
  Implement steps 7-8.  This includes all cnd_* functions, associated
  tests and reference documentation.
July 21 - August 3:
  Implement 9-10.  These are the odds and ends functions.  They will be
  completed, along with supporting tests and reference documentation.

"Pencils down"

August 4-17:
  Final overarching "tutorial-style" documentation to provide an easy
  introduction to the API.  This period is also the time for final code
  cleaning, reference documentation touch ups and another round of test
  writing to ensure that code is well covered.  Lastly, this period
  serves as a buffer zone if behind schedule.

August 18:
  Coding period ends.  By this time all of the deliverables have been
  completed.  The code compiles and runs, passing all tests.  The
  documentation is also in this state, all documentation builds
  successfully and is well written and through.

As you can see this project is very doable in the specified time frame.
 The above schedule is very generous and by taking a segmented approach
it is easy to ensure that progress is on track.  Throughout the summer a
git repository will be kept up-to-date with the current work.  This
allows anyone to see how the work is progressing, as well as giving the
community to try out the code before it is released.

Communication
-------------

I stay well connected throughout the day and a strong source of contact
is email, I receive messages in seconds and am notified on all my
devices.  I will also idle on glibc IRC often and for sure any time I am
working so that I can be reached quickly and have back and forth
conversations.  In addition to those two methods I also have a good
quality microphone so voice and video chats over XMPP or mumble are a
great solution for conversations, especially for feedback from mentors
and other situations where speaking is very useful.

I will also remain subscribed to the libc-alpha and summer-of-code
mailing lists where I can stay in touch with the community.  This is a
great area for public discussions so that I can ensure that the
decisions made in the implementation are inline with the general
communities goals and ideas.

While I can always be reached communication is always helpful to ensure
that both my mentor and myself are up-to-date with the progress.  In
order to maintain this contact I will have weekly updates with my
mentor.  Once a mentor is assigned I will discuss with them and discuss
what day and time works best for this meeting.  I think that this
meeting would be best either IRC or voice but I would also record
"minutes" and send them to my mentor via email to ensure that nothing
gets forgotten.

Qualification
-------------

I am currently in my second year of Software Engineering at Carleton
University.  By the summer I will have moved into third year standing.
 I am enthusiastic, outgoing and love to learn.  I always hold myself to
the highest standards and only consider a job done once it is done well.
 I have experience in open source communities submitting patches to a
number of projects as well as maintaining a popular free Firefox addon
Searchbar Autosizer.

This project particular appealed to me for a number of reasons.  The
first reason was because of the massive respect I have for the GNU
project as a whole, both in ideals and implementation.  I agree with
their vision of freedom and want to help them out.  By adding a feature
to such a core product as glibc I will be creating software that runs on
millions of devices around the would and improves the life of many people.

Secondly this project is well suited for my skill set.  I am well versed
in C as it was the first language I learned and still my favorite to
this day.  I particularly enjoy low level work and a libc implementation
is perfect for that interest.

Lastly I have used the pthread API many times in the past and have a
strong grasp of the concepts.  Since this project is about mapping the
C11 threads API onto pthreads this knowledge is very useful and will
allow be to get started very quickly and work efficiently.

Furthermore I have been using the tools of the GNU ecosystem for many
years.  I have been using GNU/Linux for over 7 years and have built many
software projects using the GNU build system making it second nature to
me.  I also use git daily and am comfortable using to both to record my
changes and to present them in a useful manor either via pull request or
patch.

Attachment: signature.asc
Description: OpenPGP digital signature