/* vim: set ts=4 sw=4 tw=99 et:

 *

 * Copyright (C) 2012 David Anderson

 *

 * This file is part of JITCraft.

 *

 * JITCraft is free software: you can redistribute it and/or modify it under

 * the terms of the GNU General Public License as published by the Free

 * Software Foundation, either version 3 of the License, or (at your option)

 * any later version.

 * 

 * Foobar is distributed in the hope that it will be useful, but WITHOUT ANY

 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License along with

 * JITCraft. If not, see http://www.gnu.org/licenses/.

 */

#ifndef _include_jitcraft_heap_h_

#define _include_jitcraft_heap_h_

#include "Utility.h"

#include "Spaces.h"

#include "Barriers.h"

#include "Objects.h"

#include "Handles.h"

namespace jc {

class Zone;

// Heap-allocated objects go here. Heaps are thread-local. The heap contains

// four spaces:

//

//    LIFO Space:  Used for objects that may be stack-allocated.

//    New Space:   Used for objects that are expected to be short-lived.

//    Old Space:   Used for objects that are expected to be long-lived, or that

//                 survive one collection.

//    Large Space: Used for objects that are so large they should never be

//                 moved between spaces.

//

// The garbage collector is both incremental and generational. Marking is

// performed incrementally, interleaved with program execution. Minor

// collections are also performed to mitigate the potential necessity of

// major collections.

//

// MINOR COLLECTIONS (also called "scavenges") are usually performed when the

//   new space reaches maximum capacity. During a minor collection, all live

//   objects in the new space are moved into the old space. Then, the new space

//   is reset such that it is empty.

//

//   The new is split into contiguous halves. When both halves reach maximum

//   capacity, a scavenge is performed on the older half. Thus, allocation is

//   only ever performed in one half at a time, to give newer objects a chance

//   to die.

//

//   Scavenges are beneficial for two major reasons:

//    (1) Allocation from the new space is just a pointer bump.

//    (2) Only the root set and remembered sets need to visited.

//

//   The "remembered set" is a list of all pointers that reach into the new

//   space, but come from the Old or Large spaces. The remembered set is

//   maintained via write barriers, and if it becomes full, entire chunks

//   are marked as requiring traversal.

//

//   The root and remembered sets must be visited twice: once to determine

//   which objects in the new space are live, and again to update any

//   references after the new space has been reclaimed.

//

//   Live objects in the LIFO space are always deeply traversed for pointers

//   into the new space, since it would be too difficult to maintain a working

//   remembered set.

//

// MAJOR COLLECTIONS are performed periodically, when either a given memory

//   threshold has been reached, or when requested by the host application.

//   They are also performed if no memory can be allocated.

//

//   Major collections are extremely slow; they require full heap traversal,

//   which can take more than a second on very large heaps. However, they

//   have the greatest chance at reclaiming all syntactically dead objects.

//

// SWEEPING is performed after major collections. The free space in between

//   live objects is added to a free list. Tenured allocations are then

//   performed in the free space, if possible.

//

class Heap

{

    Zone *zone_;

    HeapStack lifoSpace_;

    OldSpace mapSpace_;

    OldSpace oldSpace_;

    LargeObjectSpace largeSpace_;

    Map *metaMap_;

  public:

    enum Tenure {

        // Default, objects go into the nursery.

        Tenure_Default,

        // If objects are proven to not escape the stack, they can go into

        // a LIFO arena. Allocation on the LIFO arena is not guaranteed to

        // succeed; thus, objects may still be allocated in other arenas.

        Tenure_Stack,

        // Objects that should not go into the nursery (i.e. are expected

        // to be long-living) go here.

        Tenure_Old

    };

  private:

    inline Address newLargeObject(size_t bytes);

    inline Address newOldObject(size_t bytes);

    inline Address newStackObject(size_t bytes);

    inline Address newObject(size_t bytes, Tenure pretenure);

    void mark();

  public:

    Heap(Zone *zone);

    bool initialize();

    inline Object *allocate(Handle<Map> map, size_t byes, Tenure pretenure);

    Map *allocateMap(MapKind kind, size_t bytes);

    Map *metaMap() {

        return metaMap_;

    }

    inline Address lifoPosition() const {

        return lifoSpace_.position();

    }

    inline void unwindLifo(Address to) {

        lifoSpace_.unwind(to);

    }

    // Perform a full garbage collection.

    void reclaim();

};

}

#endif //_include_jitcraft_heap_h_