Skip to content
Permalink
Browse files

Update documentation

  • Loading branch information...
pitr-ch committed Apr 17, 2017
1 parent b2cd7e4 commit ffe427db03950ad1d780cfd49c4bbc7ee2729995
@@ -1,10 +1,12 @@
# Contributing to Concurrent Ruby

You want to contribute? Thank you! Concurrent Ruby is work of [many contributors](https://github.com/ruby-concurrency/concurrent-ruby/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/ruby-concurrency/concurrent-ruby/pulls), [propose features and discuss issues](https://github.com/ruby-concurrency/concurrent-ruby/issues). When in doubt, ask a question in the [Concurrent Ruby gitter.im chatroom](https://gitter.im/ruby-concurrency/concurrent-ruby) or on the [mailing list](https://groups.google.com/forum/#!forum/concurrent-ruby).
You want to contribute? Thank you! Concurrent Ruby is work of [many contributors](https://github.com/ruby-concurrency/concurrent-ruby/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/ruby-concurrency/concurrent-ruby/pulls), [propose features and discuss issues](https://github.com/ruby-concurrency/concurrent-ruby/issues). When in doubt, ask a question in the [Concurrent Ruby gitter.im chatroom](https://gitter.im/ruby-concurrency/concurrent-ruby).

#### Find Something to Work on

If you want to contribute but aren't sure what to work on, we keep our list of current todos on our [issues page](https://github.com/ruby-concurrency/concurrent-ruby/issues). Before starting, feel free to chat with us on [gitter](https://gitter.im/ruby-concurrency/concurrent-ruby).
If you want to contribute but aren't sure what to work on, there are tasks marked with [**looking-for-contributor**](https://github.com/ruby-concurrency/concurrent-ruby/issues?q=is%3Aissue+is%3Aopen+label%3Alooking-for-contributor) label. Complete list of tasks can be found on [issues page](https://github.com/ruby-concurrency/concurrent-ruby/issues). We appreciate your help.

Before starting, feel free to chat with us on [gitter](https://gitter.im/ruby-concurrency/concurrent-ruby).

#### Fork the Project

@@ -52,12 +54,12 @@ Make sure that `bundle exec rake` completes without errors.

#### Follow the Guidelines

There are a few very strong guidelines which we follow when adding features. Submissions which fail to follow these guidelines will likely be rejected or will require modification before acceptance.
There are a few guidelines which we follow when adding features. Consider that submissions which do not follow these guidelines will require modification before acceptance.

* **No downstream dependencies:** Concurrent Ruby is a foundational library used by major projects like [Rails](http://rubyonrails.org/). Our downstream dependencies become everyone's dependencies. Because we cannot guarantee that downstream projects meet our development standards, it's best for everyone if we simply aviod dependencies.
* **Do not monkey patch Ruby:** Changing Ruby for our convenience affects every gem in every project that uses Concurrent Ruby. Monkey patching Ruby may change the behavior of other libraries in unexpected ways and destabilize projects which depend on us.
* **Do not pollute the global namespace:** Putting all our code within the `Concurrent` module guarantees that there will be no namespace collisions with other gems or the projects which depend on us.
* **No global varaibles:** Global state should be kept to an absolute minimum. When it's necessary, add it to the global gem configuration.
* **No global state:** We are removing global state we have.
* **Minimize per-object configuration:** Ruby makes programmers happy. One of Ruby's charms is its simplicity. Concurrent Ruby aims to mirror this simplicity. Advanced configuration options are encouraged when they provide value, but every abstraction should have reasonable defaults that meet the needs of most users.
* **Provide explicit behavior and guarantees:** Our APIs should be concrete and clearly define what they do (and don't do). Users of Concurrent Ruby should never be surprised by unexpected behavior or be given guarantees we cannot keep.
* **Eat our own dog food:** Concurrent Ruby provides a rich set of low-level (internal and public) classes which provide strong guarantees and are optimized for performance across platforms. All our high-level abstractions should make use of these tools.
@@ -102,20 +104,13 @@ git rebase upstream/master
git push origin my-feature-branch -f
```

#### Update CHANGELOG Again
#### Update CHANGELOG

Update the [CHANGELOG](CHANGELOG.md) with a description of what you have changed.

Amend your previous commit and force push the changes.

```
git commit --amend
git push origin my-feature-branch -f
```

#### Check on Your Pull Request

Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI and AppVeyor. Everything should look green, otherwise fix issues and amend your commit as described above.
Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI and AppVeyor. Everything should look green, otherwise fix issues (amending your commit).

Please note that testing concurrency is hard. Very hard. We have a few tests that occasionally fail due (mostly) to incorrect synchronization within the test itself. If everything passes locally but you see an error on CI, it's possibly you've become victim to one of the tests. Don't worry, the Concurrent Ruby team reviews the tests output of all failed CI runs and will let you know if the failing test is unrelated to your commit.

@@ -1,22 +1,71 @@
# Contributor Code of Conduct
# Contributor Covenant Code of Conduct

As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
## Our Pledge

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project
a harassment-free experience for *everyone*.

## Our Standards

Examples of behavior that contributes to creating a positive environment
include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the project
* Showing empathy towards other project members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery
* Personal attacks
* Trolling or insulting/derogatory comments
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing other's private information, such as physical or electronic addresses, without explicit permission
* Other unethical or unprofessional conduct.
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project. Examples of
representing a project include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at `concurrent-ruby-conduct@pitr.ch`. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.

This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
## Attribution

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]

This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/
@@ -20,20 +20,23 @@ and classic concurrency patterns.

The design goals of this gem are:

* Be an 'unopinionated' toolbox that provides useful utilities without
debating which is better or why
* Be an 'unopinionated' toolbox that provides useful utilities without debating which is better
or why
* Remain free of external gem dependencies
* Stay true to the spirit of the languages providing inspiration
* But implement in a way that makes sense for Ruby
* Keep the semantics as idiomatic Ruby as possible
* Support features that make sense in Ruby
* Exclude features that don't make sense in Ruby
* Be small, lean, and loosely coupled
* Thread-safety
* Backward compatibility

## Contributing

**This gem depends on contributions and we appreciate your help. Would you like to contribute?
Great! Have a look at
**This gem depends on
[contributions](https://github.com/ruby-concurrency/concurrent-ruby/graphs/contributors) and we
appreciate your help. Would you like to contribute? Great! Have a look at
[issues with `looking-for-contributor` label](https://github.com/ruby-concurrency/concurrent-ruby/issues?q=is%3Aissue+is%3Aopen+label%3Alooking-for-contributor).**

## Thread Safety
@@ -55,15 +58,31 @@ other Ruby library, many of which support the mantra of
Concurrent Ruby is also the only Ruby library which provides a full suite of thread safe and
immutable variable types and data structures.

We've also initiated discussion to document [memory model](doc/synchronization.md) of Ruby which
would provide consistent behaviour and guarantees on all three of the main Ruby interpreters
(MRI/CRuby, JRuby, Rubinius, TruffleRuby).

## Features & Documentation

**The primary site for documentation is the automatically generated
[API documentation](http://ruby-concurrency.github.io/concurrent-ruby/frames.html) which is up to
date with latest release.** This readme matches the master so may contain new stuff not yet
released.

We also have a [mailing list](http://groups.google.com/group/concurrent-ruby)
and [IRC (gitter)](https://gitter.im/ruby-concurrency/concurrent-ruby).
We also have a [IRC (gitter)](https://gitter.im/ruby-concurrency/concurrent-ruby).

### Versioning

* `concurrent-ruby` uses [Semantic Versioning](http://semver.org/)
* `concurrent-ruby-ext` has always same version as `concurrent-ruby`
* `concurrent-ruby-edge` will always be 0.y.z therefore following
[point 4](http://semver.org/#spec-item-4) applies *"Major version zero
(0.y.z) is for initial development. Anything may change at any time. The
public API should not be considered stable."* However we additionally use
following rules:
* Minor version increment means incompatible changes were made
* Patch version increment means only compatible changes were made


#### General-purpose Concurrency Abstractions

@@ -191,17 +210,17 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m

* [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html): Implements
the Actor Model, where concurrent actors exchange messages.
Status: Partial documentation and tests; depends on new future/promise framework; stability is good.
*Status: Partial documentation and tests; depends on new future/promise framework; stability is good.*
* [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/Channel.html):
Communicating Sequential Processes ([CSP](https://en.wikipedia.org/wiki/Communicating_sequential_processes)).
Functionally equivalent to Go [channels](https://tour.golang.org/concurrency/2) with additional
inspiration from Clojure [core.async](https://clojure.github.io/core.async/).
Status: Partial documentation and tests.
*Status: Partial documentation and tests.*
* [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
* [LockFreeLinkedSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
Status: will be moved to core soon.
*Status: will be moved to core soon.*
* [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LockFreeStack.html)
Status: missing documentation and tests.
*Status: missing documentation and tests.*

## Supported Ruby versions

@@ -220,6 +239,8 @@ Everything within this gem can be loaded simply by requiring it:
require 'concurrent'
```

*Requiring only specific abstractions from Concurrent Ruby is not yet supported.*

To use the tools in the Edge gem it must be required separately:

```ruby
@@ -295,19 +316,22 @@ best practice is to depend on `concurrent-ruby` and let users to decide if they

## Maintainers

* [**Petr Chalupa**](https://github.com/pitr-ch) (lead maintainer)
* [Petr Chalupa](https://github.com/pitr-ch) (lead maintainer, point-of-contact)
* [Jerry D'Antonio](https://github.com/jdantonio) (creator)
* [Michele Della Torre](https://github.com/mighe)
* [Chris Seaton](https://github.com/chrisseaton)
* [Paweł Obrok](https://github.com/obrok)
* [Lucas Allan](https://github.com/lucasallan)

### Special Thanks

* [Brian Durand](https://github.com/bdurand) for the `ref` gem
* [Charles Oliver Nutter](https://github.com/headius) for the `atomic` and `thread_safe` gems
* [thedarkone](https://github.com/thedarkone) for the `thread_safe` gem

### Maintainer of the past

* [Michele Della Torre](https://github.com/mighe)
* [Paweł Obrok](https://github.com/obrok)
* [Lucas Allan](https://github.com/lucasallan)

## License and Copyright

*Concurrent Ruby* is free software released under the
@@ -12,7 +12,7 @@ module Concurrent

# {include:file:doc/actor/main.md}
# @api Actor
# @!macro edge_warning
# @!macro warn.edge
module Actor

require 'concurrent/actor/type_check'
@@ -9,7 +9,7 @@
module Concurrent

# {include:file:doc/channel.md}
# @!macro edge_warning
# @!macro warn.edge
class Channel
extend Forwardable
include Enumerable
@@ -15,7 +15,7 @@ module Concurrent
# features should remain in this module until merged into the core gem. This
# will prevent namespace collisions.
#
# @!macro [attach] edge_warning
# @!macro [attach] warn.edge
# @api Edge
# @note **Edge Features** are under active development and may change frequently.
#
@@ -14,7 +14,7 @@ module Concurrent
# end
# sleep 0.1
# cancellation.cancel # Stop the thread by cancelling
# @!macro edge_warning
# @!macro warn.edge
class Cancellation < Synchronization::Object
safe_initialization!

@@ -133,7 +133,7 @@ def initialize(cancel)
end
end

# FIXME (pitr-ch 27-Mar-2016): cooperation with mutex, condition, select etc?
# TODO (pitr-ch 27-Mar-2016): cooperation with mutex, condition, select etc?
# TODO (pitr-ch 27-Mar-2016): examples (scheduled to be cancelled in 10 sec)
end
end
@@ -18,7 +18,7 @@ module Edge
#
# This algorithm is a variation of the Nonblocking Linked Set found in
# 'The Art of Multiprocessor Programming' by Herlihy and Shavit.
# @!macro edge_warning
# @!macro warn.edge
class LockFreeLinkedSet
include Enumerable

@@ -13,7 +13,7 @@ module Concurrent
# values = actors.map(&:termination).map(&:value)
# values[0,5] # => [1, 2, 3, 4, 5]
# values[-5, 5] # => [49996, 49997, 49998, 49999, 50000]
# @!macro edge_warning
# @!macro warn.edge
class ProcessingActor < Synchronization::Object
# TODO (pitr-ch 18-Dec-2016): (un)linking, bidirectional, sends special message, multiple link calls has no effect,
# TODO (pitr-ch 21-Dec-2016): Make terminated a cancellation token?
@@ -48,7 +48,7 @@ module Concurrent
# @!macro throttle.example.throttled_future
# @!macro throttle.example.throttled_future_chain
# @!macro throttle.example.throttled_block
# @!macro edge_warning
# @!macro warn.edge
class Throttle < Synchronization::Object
# TODO (pitr-ch 21-Dec-2016): consider using sized channel for implementation instead when available

0 comments on commit ffe427d

Please sign in to comment.
You can’t perform that action at this time.