The Tor Browser / file revision

 // Copyright (c) 2010 The Chromium Authors. All rights reserved.

 // Use of this source code is governed by a BSD-style license that can be

 // found in the LICENSE file.

 #ifndef SANDBOX_SRC_SHARED_HANDLES_H__

 #define SANDBOX_SRC_SHARED_HANDLES_H__

 #include "base/basictypes.h"

 #ifndef HANDLE

 // We can provide our own windows compatilble handle definition, but

 // in general we want to rely on the client of this api to include

 // the proper windows headers. Note that we don't want to bring the

 // whole <windows.h> into scope if we don't have to.

 typedef void* HANDLE;

 #endif

 namespace sandbox {

 // SharedHandles is a simple class to stash and find windows object handles

 // given a raw block of memory which is shared between two processes.

 // It addresses the need to communicate a handle value between two windows

 // processes given that they are already sharing some memory.

 //

 // This class is not exposed directly to users of the sanbox API, instead

 // we expose the wrapper methods TargetProcess::TransferHandle( ) and

 // TargetServices::GetTransferHandle()

 //

 // Use it for a small number of items, since internaly uses linear seach

 //

 // The use is very simple. Given a shared memory between proces A and B:

 // process A:

 //  HANDLE handle = SomeFunction(..);

 //  SharedHandles shared_handes;

 //  shared_handles.Init(memory)

 //  shared_handles.SetHandle(3, handle);

 //

 // process B:

 //  SharedHandles shared_handes;

 //  shared_handles.Init(memory)

 //  HANDLE handle = shared_handles.GetHandle(3);

 //

 // Note that '3' in this example is a unique id, that must be agreed before

 // transfer

 //

 // Note2: While this class can be used in a single process, there are

 // better alternatives such as STL

 //

 // Note3: Under windows a kernel object handle in one process does not

 // make sense for another process unless there is a DuplicateHandle( )

 // call involved which this class DOES NOT do that for you.

 //

 // Note4: Under windows, shared memory when created is initialized to

 // zeros always. If you are not using shared memory it is your responsability

 // to zero it for the setter process and to copy it to the getter process.

 class SharedHandles {

  public:

   SharedHandles();

   // Initializes the shared memory for use.

   // Pass the shared memory base and size. It will internally compute

   // how many handles can it store. If initialization fails the return value

   // is false.

   bool Init(void* raw_mem, size_t size_bytes);

   // Sets a handle in the shared memory for transfer.

   // Parameters:

   // tag : an integer, different from zero that uniquely identfies the

   // handle to transfer.

   // handle: the handle value associated with 'tag' to tranfer

   // Returns false if there is not enough space in the shared memory for

   // this handle.

   bool SetHandle(uint32 tag, HANDLE handle);

   // Gets a handle previously stored by SetHandle.

   // Parameters:

   // tag: an integer different from zero that uniquely identfies the handle

   // to retrieve.

   // *handle: output handle value if the call was succesful.

   // If a handle with the provided tag is not found the return value is false.

   // If the tag is found the return value is true.

   bool GetHandle(uint32 tag, HANDLE* handle);

  private:

   // A single item is the tuple handle/tag

   struct SharedItem {

     uint32 tag;

     void* item;

   };

   // SharedMem is used to layout the memory as an array of SharedItems

   struct SharedMem {

     size_t max_items;

     SharedItem* items;

   };

   // Finds an Item tuple provided the handle tag.

   // Uses linear search because we expect the number of handles to be

   // small (say less than ~100).

   SharedItem* FindByTag(uint32 tag);

   SharedMem shared_;

   DISALLOW_COPY_AND_ASSIGN(SharedHandles);

 };

 }  // namespace sandbox

 #endif  // SANDBOX_SRC_SHARED_HANDLES_H__