{"action":"created","comment":{"url":"https://api.github.com/repos/BlueBrain/Brion/pulls/comments/57012260","id":57012260,"diff_hunk":"@@ -0,0 +1,289 @@\n+\\Redesign of the SpikeReport and Spikes container\n+============\n+\n+The current design of the SpikeReport has several flaws that need to be\n+addressed:\n+* It doesn't allow partial loading for file based reports.\n+* It exposes too many details of the stream case which can probably be hidden.\n+* The container class is a std::multimap while it could simply be a sorted array\n+  because no insertion is needed.\n+This specification proposes a new API to address these defficiencies as well\n+as include new requirements that need to be fulfilled.\n+\n+## Requirements\n+\n+The high level requirements for the replacement are listed below. Note that\n+all these requirements do not need to be directly satisfied by\n+brion::SpikeReport, but it must be possible to do so by a higher level class\n+based on it.\n+\n+* Provide a container for spikes which is sorted by timestamp, storage\n+  efficient, and random accessible at the <sup>n</sup>th position in amortized\n+  constant time (provided the data has been already fetched). This is basically\n+  a std::vector, but only read access is needed.\n+\n+* Allow partial data loading for file access.\n+\n+* Allow the selection of a subset of the cells present in the data source to be\n+  reported. In stream-based reports this information should be made available\n+  to the sender to allow filtering at the source. In the ZeroEQ implementation,\n+  the same channel needed for communicating the desired target could be used\n+  for the handshaking required to ensure that the first spikes are not missed.\n+\n+* As few details as possible should that are specific to streams should be\n+  exposed. This means that it should be easy to write client code that works\n+  the same for both file based and stream based reports without special\n+  conditions for stream based reports.\n+\n+* For stream reports the user will be able to:\n+ * Retrieve all the data until the end of stream in a simple loop without doing\n+   any active wait (blocking calls are allowed).\n+ * Know if the end of stream has been reached.\n+ * Get all the data received so far without locking.\n+ * Get information about the latest timestamp reached by the source in the\n+   sender side even when there are no spikes at all (currently if the spike\n+   report is completely empty it's not possible to make any progress until the\n+   producer reaches the end of the report).\n+\n+* When data for a time interval is requested, the time intervals are always\n+  closed on the left and open on the right.\n+\n+## General remarks\n+\n+It has been agreed that unifying both the file and the stream cases under\n+a stream-like interface (in the sense of std::iostream or POSIX file descriptor\n+IO) seems to be the best abstraction at the lower level. Providing random\n+access and out-of-core support is complicated at the lower level because\n+internal buffering is needed and this can only be implementated efficiently if\n+some assumptions about how client code will use the API are made. The most\n+important characteristic of the current proposal is that read operations  only\n+moves forward, so each operation starts where the previous one left over.\n+This way there is no need to make any distinction between the file and stream\n+based cases. Random access can still be supported adding a seek function.\n+\n+The current proposal defers important design decisions to the higher level API,\n+but the its benefit is that it provides a relatively simply API for the most\n+critical part.\n+\n+## API\n+\n+Thread-safey is only guaranteed for const access.\n+\n+### Helper types\n+\n+    struct Spike\n+    {\n+        Spike( float timestamp_, uint32_t gid_ );\n+        float timestamp;\n+        uint32_t gid;\n+    };\n+\n+    typedef std::vector< Spike > Spikes;\n+    typedef boost::shared_ptr< Spikes > SpikesPtr;\n+\n+### SpikeReport\n+\n+    SpikeReport : public boost::noncopyable\n+    {\n+    public:\n+        SpikeReport( const URI& uri, int mode );\n+\n+        /*\n+         * Open a report in read mode with a subset selection.\n+         *\n+         * @param uri\n+         * @param subset The set of gids to be reported. This set should be\n+         *        understood as a filter: any included GID which is not\n+         *        actually part of the report will be silently ignored.\n+         */\n+        SpikeReport( const URI& uri, const GIDSet& subset );\n+\n+        /**\n+         * Release all resources.\n+         * Any threads waiting on futures will return immediately and calling\n+         * get will throw a runtime_exception.\n+         */\n+        ~SPikeReport();\n+\n+        const URI& getURI();\n+\n+        /** ? */\n+        float getStartTime() const;\n+        float getEndTime() const;\n+\n+        /**\n+         * @return the end time of the latest complete read/write operation or\n+         *         UNDEFINED_TIMESTAMP if no operation has been issued.\n+         *\n+         * Operations are deemed as complete when the returned future is ready.\n+         *\n+         * The time inverval to which getCurrentTime refers is open on the\n+         * right. That means that no read of write operation may return or take\n+         * a timestamp < getCurrentTime().\n+         */\n+        float getCurrentTime() const;\n+\n+        /**\n+         * Read spikes until getCurrentTime becomes > min, the end of the source\n+         * is reached or closed.\n+         *\n+         * Preconditions:\n+         * - r.getState() is 0 or ENDED.\n+         * - The report was open in read mode.\n+         * - There is no previous read operation with a pending future.\n+         * - min >= getCurrentTime() or UNDEFINED_TIMESTAMP.\n+         * Throw std::logic_error if one of the preconditions is not fulfilled.\n+         *\n+         * Postconditions:\n+         * Let:\n+         *  - r be the SpikeReport\n+         *  - f be the returned future by r.read(min)\n+         *  - and s = r.getCurrentTime() before read is called or -inf if\n+         *    undefined:\n+         * After f.wait() returns the following are all true:\n+         *  - r.getCurrentTime() >= s\n+         *  - If r.getState() == 0, then r.getCurrentTime() > min\n+         *  - For each spike timestamp t_s in f.get(),\n+         *    s <= t_s < r.getCurrentTime() (Note this could collapse to an\n+         *    empty interval is r.getState() != 0)\n+         *\n+         * After successful f.wait_for or f.wait_until, the result is the same\n+         * as above. If they time out, no observable state changes.\n+         *\n+         * If the state is FAILED when read is called the result is undefined.\n+         *\n+         * @param min The minimum end time until which spikes will be read. If\n+         *        UNDEFINED_TIMESTAMP, it will be considered as infinite.\n+         */\n+        boost::future< Spikes > read( float min );\n+\n+        /**\n+         * Read all available spikes.\n+         *\n+         * This is a convenience function that behaves like:\n+         * read( -inf ) is getCurrentTime() is undefined and\n+         * read( getCurrentTime( )) otherwise.\n+         */\n+        boost::future< Spikes > read();\n+\n+        enum StateFlags { ENDED = 1, FAILED = 2 };","path":"doc/feature/spikeReport.md","position":null,"original_position":169,"commit_id":"91cb31c5b1d4e609450e805d328bcb654718ff45","original_commit_id":"11b6e777e6c1cb229cf1733a1adc2bcc29da312e","user":{"login":"bilgili","id":1157568,"avatar_url":"https://avatars.githubusercontent.com/u/1157568?v=3","gravatar_id":"","url":"https://api.github.com/users/bilgili","html_url":"https://github.com/bilgili","followers_url":"https://api.github.com/users/bilgili/followers","following_url":"https://api.github.com/users/bilgili/following{/other_user}","gists_url":"https://api.github.com/users/bilgili/gists{/gist_id}","starred_url":"https://api.github.com/users/bilgili/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bilgili/subscriptions","organizations_url":"https://api.github.com/users/bilgili/orgs","repos_url":"https://api.github.com/users/bilgili/repos","events_url":"https://api.github.com/users/bilgili/events{/privacy}","received_events_url":"https://api.github.com/users/bilgili/received_events","type":"User","site_admin":false},"body":"I mean two states at the same time.","created_at":"2016-03-22T15:54:00Z","updated_at":"2016-03-22T15:54:00Z","html_url":"https://github.com/BlueBrain/Brion/pull/44#discussion_r57012260","pull_request_url":"https://api.github.com/repos/BlueBrain/Brion/pulls/44","_links":{"self":{"href":"https://api.github.com/repos/BlueBrain/Brion/pulls/comments/57012260"},"html":{"href":"https://github.com/BlueBrain/Brion/pull/44#discussion_r57012260"},"pull_request":{"href":"https://api.github.com/repos/BlueBrain/Brion/pulls/44"}}},"pull_request":{"url":"https://api.github.com/repos/BlueBrain/Brion/pulls/44","id":61100297,"html_url":"https://github.com/BlueBrain/Brion/pull/44","diff_url":"https://github.com/BlueBrain/Brion/pull/44.diff","patch_url":"https://github.com/BlueBrain/Brion/pull/44.patch","issue_url":"https://api.github.com/repos/BlueBrain/Brion/issues/44","number":44,"state":"open","locked":false,"title":"Specification document for a new SpikeReport API.","user":{"login":"hernando","id":791427,"avatar_url":"https://avatars.githubusercontent.com/u/791427?v=3","gravatar_id":"","url":"https://api.github.com/users/hernando","html_url":"https://github.com/hernando","followers_url":"https://api.github.com/users/hernando/followers","following_url":"https://api.github.com/users/hernando/following{/other_user}","gists_url":"https://api.github.com/users/hernando/gists{/gist_id}","starred_url":"https://api.github.com/users/hernando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hernando/subscriptions","organizations_url":"https://api.github.com/users/hernando/orgs","repos_url":"https://api.github.com/users/hernando/repos","events_url":"https://api.github.com/users/hernando/events{/privacy}","received_events_url":"https://api.github.com/users/hernando/received_events","type":"User","site_admin":false},"body":"","created_at":"2016-02-29T16:05:29Z","updated_at":"2016-03-22T15:54:00Z","closed_at":null,"merged_at":null,"merge_commit_sha":"327cc682f57d02ce8551268f2053bbe42cc809fc","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/BlueBrain/Brion/pulls/44/commits","review_comments_url":"https://api.github.com/repos/BlueBrain/Brion/pulls/44/comments","review_comment_url":"https://api.github.com/repos/BlueBrain/Brion/pulls/comments{/number}","comments_url":"https://api.github.com/repos/BlueBrain/Brion/issues/44/comments","statuses_url":"https://api.github.com/repos/BlueBrain/Brion/statuses/91cb31c5b1d4e609450e805d328bcb654718ff45","head":{"label":"hernando:spike_report","ref":"spike_report","sha":"91cb31c5b1d4e609450e805d328bcb654718ff45","user":{"login":"hernando","id":791427,"avatar_url":"https://avatars.githubusercontent.com/u/791427?v=3","gravatar_id":"","url":"https://api.github.com/users/hernando","html_url":"https://github.com/hernando","followers_url":"https://api.github.com/users/hernando/followers","following_url":"https://api.github.com/users/hernando/following{/other_user}","gists_url":"https://api.github.com/users/hernando/gists{/gist_id}","starred_url":"https://api.github.com/users/hernando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hernando/subscriptions","organizations_url":"https://api.github.com/users/hernando/orgs","repos_url":"https://api.github.com/users/hernando/repos","events_url":"https://api.github.com/users/hernando/events{/privacy}","received_events_url":"https://api.github.com/users/hernando/received_events","type":"User","site_admin":false},"repo":{"id":36439822,"name":"Brion","full_name":"hernando/Brion","owner":{"login":"hernando","id":791427,"avatar_url":"https://avatars.githubusercontent.com/u/791427?v=3","gravatar_id":"","url":"https://api.github.com/users/hernando","html_url":"https://github.com/hernando","followers_url":"https://api.github.com/users/hernando/followers","following_url":"https://api.github.com/users/hernando/following{/other_user}","gists_url":"https://api.github.com/users/hernando/gists{/gist_id}","starred_url":"https://api.github.com/users/hernando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hernando/subscriptions","organizations_url":"https://api.github.com/users/hernando/orgs","repos_url":"https://api.github.com/users/hernando/repos","events_url":"https://api.github.com/users/hernando/events{/privacy}","received_events_url":"https://api.github.com/users/hernando/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/hernando/Brion","description":"Blue Brain C++ File IO Library","fork":true,"url":"https://api.github.com/repos/hernando/Brion","forks_url":"https://api.github.com/repos/hernando/Brion/forks","keys_url":"https://api.github.com/repos/hernando/Brion/keys{/key_id}","collaborators_url":"https://api.github.com/repos/hernando/Brion/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/hernando/Brion/teams","hooks_url":"https://api.github.com/repos/hernando/Brion/hooks","issue_events_url":"https://api.github.com/repos/hernando/Brion/issues/events{/number}","events_url":"https://api.github.com/repos/hernando/Brion/events","assignees_url":"https://api.github.com/repos/hernando/Brion/assignees{/user}","branches_url":"https://api.github.com/repos/hernando/Brion/branches{/branch}","tags_url":"https://api.github.com/repos/hernando/Brion/tags","blobs_url":"https://api.github.com/repos/hernando/Brion/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/hernando/Brion/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/hernando/Brion/git/refs{/sha}","trees_url":"https://api.github.com/repos/hernando/Brion/git/trees{/sha}","statuses_url":"https://api.github.com/repos/hernando/Brion/statuses/{sha}","languages_url":"https://api.github.com/repos/hernando/Brion/languages","stargazers_url":"https://api.github.com/repos/hernando/Brion/stargazers","contributors_url":"https://api.github.com/repos/hernando/Brion/contributors","subscribers_url":"https://api.github.com/repos/hernando/Brion/subscribers","subscription_url":"https://api.github.com/repos/hernando/Brion/subscription","commits_url":"https://api.github.com/repos/hernando/Brion/commits{/sha}","git_commits_url":"https://api.github.com/repos/hernando/Brion/git/commits{/sha}","comments_url":"https://api.github.com/repos/hernando/Brion/comments{/number}","issue_comment_url":"https://api.github.com/repos/hernando/Brion/issues/comments{/number}","contents_url":"https://api.github.com/repos/hernando/Brion/contents/{+path}","compare_url":"https://api.github.com/repos/hernando/Brion/compare/{base}...{head}","merges_url":"https://api.github.com/repos/hernando/Brion/merges","archive_url":"https://api.github.com/repos/hernando/Brion/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/hernando/Brion/downloads","issues_url":"https://api.github.com/repos/hernando/Brion/issues{/number}","pulls_url":"https://api.github.com/repos/hernando/Brion/pulls{/number}","milestones_url":"https://api.github.com/repos/hernando/Brion/milestones{/number}","notifications_url":"https://api.github.com/repos/hernando/Brion/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/hernando/Brion/labels{/name}","releases_url":"https://api.github.com/repos/hernando/Brion/releases{/id}","deployments_url":"https://api.github.com/repos/hernando/Brion/deployments","created_at":"2015-05-28T13:23:07Z","updated_at":"2016-01-18T16:00:14Z","pushed_at":"2016-03-22T15:49:55Z","git_url":"git://github.com/hernando/Brion.git","ssh_url":"git@github.com:hernando/Brion.git","clone_url":"https://github.com/hernando/Brion.git","svn_url":"https://github.com/hernando/Brion","homepage":"http://bluebrain.github.io/","size":406,"stargazers_count":0,"watchers_count":0,"language":"C++","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"BlueBrain:master","ref":"master","sha":"e43d27b684dc65ab869c5e839b13a6b423416b99","user":{"login":"BlueBrain","id":1479142,"avatar_url":"https://avatars.githubusercontent.com/u/1479142?v=3","gravatar_id":"","url":"https://api.github.com/users/BlueBrain","html_url":"https://github.com/BlueBrain","followers_url":"https://api.github.com/users/BlueBrain/followers","following_url":"https://api.github.com/users/BlueBrain/following{/other_user}","gists_url":"https://api.github.com/users/BlueBrain/gists{/gist_id}","starred_url":"https://api.github.com/users/BlueBrain/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/BlueBrain/subscriptions","organizations_url":"https://api.github.com/users/BlueBrain/orgs","repos_url":"https://api.github.com/users/BlueBrain/repos","events_url":"https://api.github.com/users/BlueBrain/events{/privacy}","received_events_url":"https://api.github.com/users/BlueBrain/received_events","type":"Organization","site_admin":false},"repo":{"id":35547993,"name":"Brion","full_name":"BlueBrain/Brion","owner":{"login":"BlueBrain","id":1479142,"avatar_url":"https://avatars.githubusercontent.com/u/1479142?v=3","gravatar_id":"","url":"https://api.github.com/users/BlueBrain","html_url":"https://github.com/BlueBrain","followers_url":"https://api.github.com/users/BlueBrain/followers","following_url":"https://api.github.com/users/BlueBrain/following{/other_user}","gists_url":"https://api.github.com/users/BlueBrain/gists{/gist_id}","starred_url":"https://api.github.com/users/BlueBrain/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/BlueBrain/subscriptions","organizations_url":"https://api.github.com/users/BlueBrain/orgs","repos_url":"https://api.github.com/users/BlueBrain/repos","events_url":"https://api.github.com/users/BlueBrain/events{/privacy}","received_events_url":"https://api.github.com/users/BlueBrain/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/BlueBrain/Brion","description":"Blue Brain C++ File IO Library","fork":false,"url":"https://api.github.com/repos/BlueBrain/Brion","forks_url":"https://api.github.com/repos/BlueBrain/Brion/forks","keys_url":"https://api.github.com/repos/BlueBrain/Brion/keys{/key_id}","collaborators_url":"https://api.github.com/repos/BlueBrain/Brion/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/BlueBrain/Brion/teams","hooks_url":"https://api.github.com/repos/BlueBrain/Brion/hooks","issue_events_url":"https://api.github.com/repos/BlueBrain/Brion/issues/events{/number}","events_url":"https://api.github.com/repos/BlueBrain/Brion/events","assignees_url":"https://api.github.com/repos/BlueBrain/Brion/assignees{/user}","branches_url":"https://api.github.com/repos/BlueBrain/Brion/branches{/branch}","tags_url":"https://api.github.com/repos/BlueBrain/Brion/tags","blobs_url":"https://api.github.com/repos/BlueBrain/Brion/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/BlueBrain/Brion/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/BlueBrain/Brion/git/refs{/sha}","trees_url":"https://api.github.com/repos/BlueBrain/Brion/git/trees{/sha}","statuses_url":"https://api.github.com/repos/BlueBrain/Brion/statuses/{sha}","languages_url":"https://api.github.com/repos/BlueBrain/Brion/languages","stargazers_url":"https://api.github.com/repos/BlueBrain/Brion/stargazers","contributors_url":"https://api.github.com/repos/BlueBrain/Brion/contributors","subscribers_url":"https://api.github.com/repos/BlueBrain/Brion/subscribers","subscription_url":"https://api.github.com/repos/BlueBrain/Brion/subscription","commits_url":"https://api.github.com/repos/BlueBrain/Brion/commits{/sha}","git_commits_url":"https://api.github.com/repos/BlueBrain/Brion/git/commits{/sha}","comments_url":"https://api.github.com/repos/BlueBrain/Brion/comments{/number}","issue_comment_url":"https://api.github.com/repos/BlueBrain/Brion/issues/comments{/number}","contents_url":"https://api.github.com/repos/BlueBrain/Brion/contents/{+path}","compare_url":"https://api.github.com/repos/BlueBrain/Brion/compare/{base}...{head}","merges_url":"https://api.github.com/repos/BlueBrain/Brion/merges","archive_url":"https://api.github.com/repos/BlueBrain/Brion/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/BlueBrain/Brion/downloads","issues_url":"https://api.github.com/repos/BlueBrain/Brion/issues{/number}","pulls_url":"https://api.github.com/repos/BlueBrain/Brion/pulls{/number}","milestones_url":"https://api.github.com/repos/BlueBrain/Brion/milestones{/number}","notifications_url":"https://api.github.com/repos/BlueBrain/Brion/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/BlueBrain/Brion/labels{/name}","releases_url":"https://api.github.com/repos/BlueBrain/Brion/releases{/id}","deployments_url":"https://api.github.com/repos/BlueBrain/Brion/deployments","created_at":"2015-05-13T12:33:49Z","updated_at":"2016-01-13T08:52:11Z","pushed_at":"2016-03-22T15:49:56Z","git_url":"git://github.com/BlueBrain/Brion.git","ssh_url":"git@github.com:BlueBrain/Brion.git","clone_url":"https://github.com/BlueBrain/Brion.git","svn_url":"https://github.com/BlueBrain/Brion","homepage":"http://bluebrain.github.io/","size":394,"stargazers_count":3,"watchers_count":3,"language":"C++","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":10,"mirror_url":null,"open_issues_count":2,"forks":10,"open_issues":2,"watchers":3,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/BlueBrain/Brion/pulls/44"},"html":{"href":"https://github.com/BlueBrain/Brion/pull/44"},"issue":{"href":"https://api.github.com/repos/BlueBrain/Brion/issues/44"},"comments":{"href":"https://api.github.com/repos/BlueBrain/Brion/issues/44/comments"},"review_comments":{"href":"https://api.github.com/repos/BlueBrain/Brion/pulls/44/comments"},"review_comment":{"href":"https://api.github.com/repos/BlueBrain/Brion/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/BlueBrain/Brion/pulls/44/commits"},"statuses":{"href":"https://api.github.com/repos/BlueBrain/Brion/statuses/91cb31c5b1d4e609450e805d328bcb654718ff45"}}}}