{"action":"created","comment":{"url":"https://api.github.com/repos/densh/scala-offheap/pulls/comments/43409682","id":43409682,"diff_hunk":"@@ -0,0 +1,247 @@\n+# Offheap classes\n+\n+Off-heap classes are core abstraction that lets one define custom data structures to\n+be allocated in off-heap memory. Unlike regular classes they are completely opaque\n+to JVM's garbage collector (which sees them just as values of `Long` primitive type)\n+and incur no typical GC overhead that regular classes do.\n+\n+To allocate anything off-heap one has to provide an instance of\n+`Allocator` type that defines memory management strategy for current allocation.\n+[[Allocators]] are going to be covered in detail in the next section\n+and for now we just assume that there is one available in the scope. E.g.:\n+\n+```scala\n+scala> implicit val alloc: Allocator = malloc\n+alloc: offheap.Allocator = offheap.malloc$@23d230db\n+```\n+\n+Off-heap classes come in two varieties: `@data` classes and `@enum` classes. Both of\n+them desugar down to value classes over underlying physical address. Due to that they\n+can only be defined in statically accessible locations, may not define custom equals\n+or hashCode, have limited subset of possible members and can only extend universal traits.\n+This is a price one has to pay for efficient unboxed representation.\n+\n+## @data classes\n+\n+Data classes are a close equivalent of on-heap case classes. For example:\n+\n+```scala\n+@data class Point(x: Int, y: Int)\n+```\n+\n+Defines a data class with two immutable publicly accessible fields `x` and `y`. Data\n+classes are usually passed by reference just regular normal classes. For example if\n+we define another data class that contains two fields of `Point` type:\n+\n+```scala\n+@data class Segment(start: Point, end: Point)\n+```\n+\n+We would store two references to two points allocated somewhere. It's possible to\n+change standard by-reference semantics into by-value one using `@embed` annotion:\n+\n+```scala\n+@data class Segment2(@embed start: Point, @embed end: Point)\n+```\n+\n+Here `start` and `end` are not references to `Point` but rather actual values within\n+`Segment2` allocation. Whenever an embedded field is accessed an inner pointer for given\n+field is computed and returned as a value of given type without any extra dereferencing\n+overhead.\n+\n+Whenever and off-heap class with embed fields is instantiated using canonical constructors\n+the construction of embedded fields happens right within outer classes memory. For example\n+in the following snippet:\n+\n+```scala\n+scala> Segment2(Point(10, 20), Point(30, 40))\n+res0: Segment2 = Segment2(Point(10, 20), Point(30, 40))\n+```\n+\n+Values of `x` and `y` for `start` and `end` points are written directly into memory\n+allocated for the segment. If we were to split this code apart and allocate points\n+outside of the `Segment2` constructor:\n+\n+```scala\n+scala> val start = Point(10, 20)\n+start: Point = Point(10, 20)\n+\n+scala> val end = Point(30, 40)\n+end: Point = Point(30, 40)\n+\n+scala> Segment2(start, end)\n+res1: Segment2 = Segment2(Point(10, 20), Point(30, 40))\n+```\n+\n+The end result would be the same but the point values would first be allocated separately\n+using current allocator in scope and then copied over to segment memory. Needless to say\n+this is going to be less efficient and will allocate more memory that has to be taken care\n+off in one way or the other.\n+\n+At the moment one can only embed other off-heap classes. Primitives have embed-like\n+semantics by default. Arrays can not be embedded due to their variable size nature. We\n+plan to add support for\n+[embeddable fixed-size arrays](https://github.com/densh/scala-offheap/issues/47) in the future.\n+\n+Embed annotation only takes effect when it's used on fields of the data class and does\n+nothing if put into any other location (e.g. on local val definition.)\n+\n+**Data layout.** Fields of data class are laid out in memory in the same order\n+as they were declared. Appropriate padding is inserted between the fields so that\n+each field is aligned according to the size of its type. For example:\n+\n+```scala\n+cala> @data class XYZ(x: Byte, y: Char, z: Long)\n+defined class XYZ\n+defined object XYZ\n+```\n+\n+Is going to take 16 bytes, not 9. 1-byte padding is going to be inserted after `x` and\n+4-byte padding is going to be inserted after `y`. Reordering the fields can sometimes\n+reduce the size of the data structure.\n+\n+One can inspect layout of the data class using `sizeOfEmbed` and `offsetOf` helper\n+functions:\n+\n+```scala\n+scala> sizeOfEmbed[XYZ]\n+res1: offheap.Size = 16\n+\n+scala> offsetOf[XYZ](\"x\")\n+res2: offheap.Size = 0\n+\n+scala> offsetOf[XYZ](\"y\")\n+res3: offheap.Size = 2\n+\n+scala> offsetOf[XYZ](\"z\")\n+res4: offheap.Size = 8\n+```\n+\n+Embedded fields of type `T` are treated as a large primitive value with a `sizeOfEmbed[T]`\n+size and aligned to the size of their largest field that one can look up using\n+`alignemtOfEmbed[T]` utility function.","path":"docs/02_offheap_classes.md","position":122,"original_position":122,"commit_id":"5634c0f3bac1edd2edfa6162f00377c092c85fc6","original_commit_id":"5634c0f3bac1edd2edfa6162f00377c092c85fc6","user":{"login":"densh","id":320966,"avatar_url":"https://avatars.githubusercontent.com/u/320966?v=3","gravatar_id":"","url":"https://api.github.com/users/densh","html_url":"https://github.com/densh","followers_url":"https://api.github.com/users/densh/followers","following_url":"https://api.github.com/users/densh/following{/other_user}","gists_url":"https://api.github.com/users/densh/gists{/gist_id}","starred_url":"https://api.github.com/users/densh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/densh/subscriptions","organizations_url":"https://api.github.com/users/densh/orgs","repos_url":"https://api.github.com/users/densh/repos","events_url":"https://api.github.com/users/densh/events{/privacy}","received_events_url":"https://api.github.com/users/densh/received_events","type":"User","site_admin":false},"body":"embedded fields are aligned to the size of the largest field, это функция как раз вернет сколько именно.","created_at":"2015-10-29T16:34:13Z","updated_at":"2015-10-29T16:34:13Z","html_url":"https://github.com/densh/scala-offheap/pull/84#discussion_r43409682","pull_request_url":"https://api.github.com/repos/densh/scala-offheap/pulls/84","_links":{"self":{"href":"https://api.github.com/repos/densh/scala-offheap/pulls/comments/43409682"},"html":{"href":"https://github.com/densh/scala-offheap/pull/84#discussion_r43409682"},"pull_request":{"href":"https://api.github.com/repos/densh/scala-offheap/pulls/84"}}},"pull_request":{"url":"https://api.github.com/repos/densh/scala-offheap/pulls/84","id":49155993,"html_url":"https://github.com/densh/scala-offheap/pull/84","diff_url":"https://github.com/densh/scala-offheap/pull/84.diff","patch_url":"https://github.com/densh/scala-offheap/pull/84.patch","issue_url":"https://api.github.com/repos/densh/scala-offheap/issues/84","number":84,"state":"open","locked":false,"title":"Move docs into main repo from wiki","user":{"login":"densh","id":320966,"avatar_url":"https://avatars.githubusercontent.com/u/320966?v=3","gravatar_id":"","url":"https://api.github.com/users/densh","html_url":"https://github.com/densh","followers_url":"https://api.github.com/users/densh/followers","following_url":"https://api.github.com/users/densh/following{/other_user}","gists_url":"https://api.github.com/users/densh/gists{/gist_id}","starred_url":"https://api.github.com/users/densh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/densh/subscriptions","organizations_url":"https://api.github.com/users/densh/orgs","repos_url":"https://api.github.com/users/densh/repos","events_url":"https://api.github.com/users/densh/events{/privacy}","received_events_url":"https://api.github.com/users/densh/received_events","type":"User","site_admin":false},"body":"review @xeno-by ","created_at":"2015-10-29T15:33:12Z","updated_at":"2015-10-29T16:34:13Z","closed_at":null,"merged_at":null,"merge_commit_sha":"468a3848a102eab49e7cb4078a1fc3b03c937720","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/densh/scala-offheap/pulls/84/commits","review_comments_url":"https://api.github.com/repos/densh/scala-offheap/pulls/84/comments","review_comment_url":"https://api.github.com/repos/densh/scala-offheap/pulls/comments{/number}","comments_url":"https://api.github.com/repos/densh/scala-offheap/issues/84/comments","statuses_url":"https://api.github.com/repos/densh/scala-offheap/statuses/5634c0f3bac1edd2edfa6162f00377c092c85fc6","head":{"label":"densh:topic/docs","ref":"topic/docs","sha":"5634c0f3bac1edd2edfa6162f00377c092c85fc6","user":{"login":"densh","id":320966,"avatar_url":"https://avatars.githubusercontent.com/u/320966?v=3","gravatar_id":"","url":"https://api.github.com/users/densh","html_url":"https://github.com/densh","followers_url":"https://api.github.com/users/densh/followers","following_url":"https://api.github.com/users/densh/following{/other_user}","gists_url":"https://api.github.com/users/densh/gists{/gist_id}","starred_url":"https://api.github.com/users/densh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/densh/subscriptions","organizations_url":"https://api.github.com/users/densh/orgs","repos_url":"https://api.github.com/users/densh/repos","events_url":"https://api.github.com/users/densh/events{/privacy}","received_events_url":"https://api.github.com/users/densh/received_events","type":"User","site_admin":false},"repo":{"id":24936344,"name":"scala-offheap","full_name":"densh/scala-offheap","owner":{"login":"densh","id":320966,"avatar_url":"https://avatars.githubusercontent.com/u/320966?v=3","gravatar_id":"","url":"https://api.github.com/users/densh","html_url":"https://github.com/densh","followers_url":"https://api.github.com/users/densh/followers","following_url":"https://api.github.com/users/densh/following{/other_user}","gists_url":"https://api.github.com/users/densh/gists{/gist_id}","starred_url":"https://api.github.com/users/densh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/densh/subscriptions","organizations_url":"https://api.github.com/users/densh/orgs","repos_url":"https://api.github.com/users/densh/repos","events_url":"https://api.github.com/users/densh/events{/privacy}","received_events_url":"https://api.github.com/users/densh/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/densh/scala-offheap","description":"Type-safe off-heap memory for Scala.","fork":false,"url":"https://api.github.com/repos/densh/scala-offheap","forks_url":"https://api.github.com/repos/densh/scala-offheap/forks","keys_url":"https://api.github.com/repos/densh/scala-offheap/keys{/key_id}","collaborators_url":"https://api.github.com/repos/densh/scala-offheap/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/densh/scala-offheap/teams","hooks_url":"https://api.github.com/repos/densh/scala-offheap/hooks","issue_events_url":"https://api.github.com/repos/densh/scala-offheap/issues/events{/number}","events_url":"https://api.github.com/repos/densh/scala-offheap/events","assignees_url":"https://api.github.com/repos/densh/scala-offheap/assignees{/user}","branches_url":"https://api.github.com/repos/densh/scala-offheap/branches{/branch}","tags_url":"https://api.github.com/repos/densh/scala-offheap/tags","blobs_url":"https://api.github.com/repos/densh/scala-offheap/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/densh/scala-offheap/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/densh/scala-offheap/git/refs{/sha}","trees_url":"https://api.github.com/repos/densh/scala-offheap/git/trees{/sha}","statuses_url":"https://api.github.com/repos/densh/scala-offheap/statuses/{sha}","languages_url":"https://api.github.com/repos/densh/scala-offheap/languages","stargazers_url":"https://api.github.com/repos/densh/scala-offheap/stargazers","contributors_url":"https://api.github.com/repos/densh/scala-offheap/contributors","subscribers_url":"https://api.github.com/repos/densh/scala-offheap/subscribers","subscription_url":"https://api.github.com/repos/densh/scala-offheap/subscription","commits_url":"https://api.github.com/repos/densh/scala-offheap/commits{/sha}","git_commits_url":"https://api.github.com/repos/densh/scala-offheap/git/commits{/sha}","comments_url":"https://api.github.com/repos/densh/scala-offheap/comments{/number}","issue_comment_url":"https://api.github.com/repos/densh/scala-offheap/issues/comments{/number}","contents_url":"https://api.github.com/repos/densh/scala-offheap/contents/{+path}","compare_url":"https://api.github.com/repos/densh/scala-offheap/compare/{base}...{head}","merges_url":"https://api.github.com/repos/densh/scala-offheap/merges","archive_url":"https://api.github.com/repos/densh/scala-offheap/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/densh/scala-offheap/downloads","issues_url":"https://api.github.com/repos/densh/scala-offheap/issues{/number}","pulls_url":"https://api.github.com/repos/densh/scala-offheap/pulls{/number}","milestones_url":"https://api.github.com/repos/densh/scala-offheap/milestones{/number}","notifications_url":"https://api.github.com/repos/densh/scala-offheap/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/densh/scala-offheap/labels{/name}","releases_url":"https://api.github.com/repos/densh/scala-offheap/releases{/id}","created_at":"2014-10-08T10:47:47Z","updated_at":"2015-10-27T12:39:02Z","pushed_at":"2015-10-29T15:33:12Z","git_url":"git://github.com/densh/scala-offheap.git","ssh_url":"git@github.com:densh/scala-offheap.git","clone_url":"https://github.com/densh/scala-offheap.git","svn_url":"https://github.com/densh/scala-offheap","homepage":"","size":8760,"stargazers_count":234,"watchers_count":234,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":20,"mirror_url":null,"open_issues_count":23,"forks":20,"open_issues":23,"watchers":234,"default_branch":"master"}},"base":{"label":"densh:master","ref":"master","sha":"6ba96337e0963123c39fda95cfe4a785059733af","user":{"login":"densh","id":320966,"avatar_url":"https://avatars.githubusercontent.com/u/320966?v=3","gravatar_id":"","url":"https://api.github.com/users/densh","html_url":"https://github.com/densh","followers_url":"https://api.github.com/users/densh/followers","following_url":"https://api.github.com/users/densh/following{/other_user}","gists_url":"https://api.github.com/users/densh/gists{/gist_id}","starred_url":"https://api.github.com/users/densh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/densh/subscriptions","organizations_url":"https://api.github.com/users/densh/orgs","repos_url":"https://api.github.com/users/densh/repos","events_url":"https://api.github.com/users/densh/events{/privacy}","received_events_url":"https://api.github.com/users/densh/received_events","type":"User","site_admin":false},"repo":{"id":24936344,"name":"scala-offheap","full_name":"densh/scala-offheap","owner":{"login":"densh","id":320966,"avatar_url":"https://avatars.githubusercontent.com/u/320966?v=3","gravatar_id":"","url":"https://api.github.com/users/densh","html_url":"https://github.com/densh","followers_url":"https://api.github.com/users/densh/followers","following_url":"https://api.github.com/users/densh/following{/other_user}","gists_url":"https://api.github.com/users/densh/gists{/gist_id}","starred_url":"https://api.github.com/users/densh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/densh/subscriptions","organizations_url":"https://api.github.com/users/densh/orgs","repos_url":"https://api.github.com/users/densh/repos","events_url":"https://api.github.com/users/densh/events{/privacy}","received_events_url":"https://api.github.com/users/densh/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/densh/scala-offheap","description":"Type-safe off-heap memory for Scala.","fork":false,"url":"https://api.github.com/repos/densh/scala-offheap","forks_url":"https://api.github.com/repos/densh/scala-offheap/forks","keys_url":"https://api.github.com/repos/densh/scala-offheap/keys{/key_id}","collaborators_url":"https://api.github.com/repos/densh/scala-offheap/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/densh/scala-offheap/teams","hooks_url":"https://api.github.com/repos/densh/scala-offheap/hooks","issue_events_url":"https://api.github.com/repos/densh/scala-offheap/issues/events{/number}","events_url":"https://api.github.com/repos/densh/scala-offheap/events","assignees_url":"https://api.github.com/repos/densh/scala-offheap/assignees{/user}","branches_url":"https://api.github.com/repos/densh/scala-offheap/branches{/branch}","tags_url":"https://api.github.com/repos/densh/scala-offheap/tags","blobs_url":"https://api.github.com/repos/densh/scala-offheap/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/densh/scala-offheap/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/densh/scala-offheap/git/refs{/sha}","trees_url":"https://api.github.com/repos/densh/scala-offheap/git/trees{/sha}","statuses_url":"https://api.github.com/repos/densh/scala-offheap/statuses/{sha}","languages_url":"https://api.github.com/repos/densh/scala-offheap/languages","stargazers_url":"https://api.github.com/repos/densh/scala-offheap/stargazers","contributors_url":"https://api.github.com/repos/densh/scala-offheap/contributors","subscribers_url":"https://api.github.com/repos/densh/scala-offheap/subscribers","subscription_url":"https://api.github.com/repos/densh/scala-offheap/subscription","commits_url":"https://api.github.com/repos/densh/scala-offheap/commits{/sha}","git_commits_url":"https://api.github.com/repos/densh/scala-offheap/git/commits{/sha}","comments_url":"https://api.github.com/repos/densh/scala-offheap/comments{/number}","issue_comment_url":"https://api.github.com/repos/densh/scala-offheap/issues/comments{/number}","contents_url":"https://api.github.com/repos/densh/scala-offheap/contents/{+path}","compare_url":"https://api.github.com/repos/densh/scala-offheap/compare/{base}...{head}","merges_url":"https://api.github.com/repos/densh/scala-offheap/merges","archive_url":"https://api.github.com/repos/densh/scala-offheap/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/densh/scala-offheap/downloads","issues_url":"https://api.github.com/repos/densh/scala-offheap/issues{/number}","pulls_url":"https://api.github.com/repos/densh/scala-offheap/pulls{/number}","milestones_url":"https://api.github.com/repos/densh/scala-offheap/milestones{/number}","notifications_url":"https://api.github.com/repos/densh/scala-offheap/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/densh/scala-offheap/labels{/name}","releases_url":"https://api.github.com/repos/densh/scala-offheap/releases{/id}","created_at":"2014-10-08T10:47:47Z","updated_at":"2015-10-27T12:39:02Z","pushed_at":"2015-10-29T15:33:12Z","git_url":"git://github.com/densh/scala-offheap.git","ssh_url":"git@github.com:densh/scala-offheap.git","clone_url":"https://github.com/densh/scala-offheap.git","svn_url":"https://github.com/densh/scala-offheap","homepage":"","size":8760,"stargazers_count":234,"watchers_count":234,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":20,"mirror_url":null,"open_issues_count":23,"forks":20,"open_issues":23,"watchers":234,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/densh/scala-offheap/pulls/84"},"html":{"href":"https://github.com/densh/scala-offheap/pull/84"},"issue":{"href":"https://api.github.com/repos/densh/scala-offheap/issues/84"},"comments":{"href":"https://api.github.com/repos/densh/scala-offheap/issues/84/comments"},"review_comments":{"href":"https://api.github.com/repos/densh/scala-offheap/pulls/84/comments"},"review_comment":{"href":"https://api.github.com/repos/densh/scala-offheap/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/densh/scala-offheap/pulls/84/commits"},"statuses":{"href":"https://api.github.com/repos/densh/scala-offheap/statuses/5634c0f3bac1edd2edfa6162f00377c092c85fc6"}}}}