tools/pldt/org.eclipse.ptp.pldt.upc/src/org/eclipse/ptp/pldt/upc/editorHelp/UPCCHelpBook.java - ptp/org.eclipse.ptp - Git at Google

 /**********************************************************************
  * Copyright (c) 2008 IBM Corporation.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ptp.pldt.upc.editorHelp;

 import java.util.HashMap;
 import java.util.Map;

 import org.eclipse.cdt.ui.IFunctionSummary;
 import org.eclipse.ptp.pldt.common.editorHelp.CHelpBookImpl;
 import org.eclipse.ptp.pldt.common.editorHelp.FunctionPrototypeSummaryImpl;
 import org.eclipse.ptp.pldt.common.editorHelp.FunctionSummaryImpl;
 import org.eclipse.ptp.pldt.upc.UPCPlugin;

 /**
  * UPC help book - this is the information that is used for the hover help
  * <p>
  * <b>Note:</b> This (and F1/dynamic help as well) requires a fix to CDT post-5.0.0 release
  * to org.eclipse.cdt.internal.core.model.TranslationUnit  - to recognize content-type of UPC to be a deriviative ("kindOf") the C content type.
  * <p>See https://bugs.eclipse.org/bugs/show_bug.cgi?id=237331
  * @author Beth Tibbitts
  *
  */
 public class UPCCHelpBook extends CHelpBookImpl {
 	private static final String TITLE = "UPC C Help Book";
 	private Map<String,String> desc=new HashMap<String, String>();


 	public UPCCHelpBook() {
         super(UPCPlugin.getPluginId());
         // populate description map - this just makes the funcName2FuncInfo init lines a bit more terse

         desc.put("upc_addrfield", "Returns an implementation-defined value reflecting the <q>local address</q>of the object pointed to by the pointer-to-shared argument.");
         desc.put("upc_affinitysize", "A convenience function which calculates the exact size of the local portion of the data in a shared object with affinity to <code>threadid</code>.");
         desc.put("upc_all_alloc", "Allocates shared space");
         desc.put("upc_all_broadcast", "Copies a block of memory with affinity to a single thread to a block of shared memory on each thread.");
         desc.put("upc_all_lock_alloc", "Dynamically allocates a lock and returns a pointer to it. The lock is created in an unlocked state.");
         desc.put("upc_all_exchange", "Copies the ith block of memory from a shared memory area that has affinity to thread j to the jth block of a shared memory area that has affinity to thread i");
         desc.put("upc_all_gather",     "Copies a block of shared memory that has affinity to the ith thread to the ith block of a shared memory area that has affinity to a single thread.");
         desc.put("upc_all_gather_all", "Copies a block of memory from one shared memory area with affinity to the ith thread to the ith block of a shared memory area on each thread.");
         desc.put("upc_all_lock_alloc", "Dynamically allocates a lock and returns a pointer to it. The lock is created in an unlocked state.");
         desc.put("upc_all_permute", "Copies a block of memory from a shared memory area that has affinity to the ith thread to a block of a shared memory that has affinity to thread perm[i].");
         desc.put("upc_all_scatter", "Copies the ith block of an area of shared memory with affinity to a single thread to a block of shared memory with affinity to the ith thread.");
         desc.put("upc_alloc", "Allocates shared space of at least nbytes with affinity to the calling thread.");
         desc.put("upc_free", "Frees dynamically allocated shared storage");
         desc.put("upc_global_alloc","Allocates shared space");
         desc.put("upc_global_exit","Flushes all I/O, releases all storage, and terminates the execution for all active threads.");
         desc.put("upc_global_lock_alloc", "Dynamically allocates a lock and returns a pointer to it. The lock is created in an unlocked state.");
         desc.put("upc_local_alloc","Deprecated. Use upc_alloc instead.\nAllocates shared space.");
         desc.put("upc_lock_attempt", "Attempts to set the state of a lock to locked. Return code indicates previous state.");
         desc.put("upc_lock_free", "Frees all resources associated with a lock.");
         desc.put("upc_lock_t", "UPC type for a lock");
         desc.put("upc_lock", "Sets the state of a lock to locked.");
         desc.put("upc_memcpy", "Copies n characters from a shared object having affinity with one thread to a shared object having affinity with the same or another thread.");
         desc.put("upc_memget", "Copies n characters from a shared object with affinity to any single thread to an object on the calling thread.");
         desc.put("upc_memset", "Copies a value, converted to an unsigned char, to a shared object with affinity to any single thread.");
         desc.put("upc_phaseof", "Returns the phase component of the pointer-to-shared argument.");
         desc.put("upc_resetphase", "Returns a pointer-to-shared which is identical to its input except that it has zero phase");
         desc.put("upc_threadof", "Returns the index of the thread that has affinity to the shared object pointed to by the argument.");
         desc.put("upc_unlock", "Sets the state of a lock to unlocked.");
         desc.put("shared", "this is a shared UPC keyword");


 		// populate func map
         //funcName2FuncInfo.put("upc_free", new FunctionSummaryImpl("upc_free", "", "upc_free test description",
         //        new FunctionPrototypeSummaryImpl("upc_free", "void", "shared void *ptr"), null));
         String desc = ""; // will do map lookup for description in fps method.
         funcName2FuncInfo.put("upc_addrfield", fps("upc_addrfield", "", desc, "size_t", "shared void *ptr"));
         funcName2FuncInfo.put("upc_affinitysize", fps("upc_affinitysize", "", desc, "size_t", "size_t totalsize, size_t nbytes, size_t threadid"));
         funcName2FuncInfo.put("upc_all_alloc", fps("upc_all_alloc", "", desc, "void", "size_t nblocks, size_t nbytes"));
         funcName2FuncInfo.put("upc_all_broadcast", fps("upc_all_broadcast", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
         funcName2FuncInfo.put("upc_all_exchange", fps("upc_all_exchange", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
         funcName2FuncInfo.put("upc_all_gather_all", fps("upc_all_gather_all", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
         funcName2FuncInfo.put("upc_all_gather", fps("upc_all_gather", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
         funcName2FuncInfo.put("upc_all_lock_alloc", fps("upc_all_lock_alloc", "", desc, "upc_lock_t", "void"));
         funcName2FuncInfo.put("upc_all_permute", fps("upc_all_permute", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, shared const int * restrict perm, size_t nbytes, upc_flag_t flags"));
         funcName2FuncInfo.put("upc_all_scatter", fps("upc_all_scatter", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
         funcName2FuncInfo.put("upc_alloc", fps("upc_alloc", "", desc, "void", "size_t nbytes"));
         funcName2FuncInfo.put("upc_free", fps("upc_free", "", desc, "void", "shared void *ptr"));
         funcName2FuncInfo.put("upc_global_alloc", fps("upc_global_alloc", "", desc, "void", "int status"));
         funcName2FuncInfo.put("upc_global_exit", fps("upc_global_exit", "", desc, "void", "int status"));
         funcName2FuncInfo.put("upc_global_lock_alloc", fps("upc_global_lock_alloc", "", desc, "upc_lock_t", "void"));
         funcName2FuncInfo.put("upc_local_alloc", fps("upc_local_alloc", "", desc, "void", "size_t nblocks, size_t nbytes"));
         funcName2FuncInfo.put("upc_lock_attempt", fps("upc_lock_attempt", "", desc, "int", "upc_lock_t *ptr"));
         funcName2FuncInfo.put("upc_lock_free", fps("upc_lock_free", "", desc, "upc_lock_t", "void"));
         funcName2FuncInfo.put("upc_lock", fps("upc_lock", "", desc, "void", "upc_lock_t *ptr"));
         funcName2FuncInfo.put("upc_memcpy", fps("upc_memcpy", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t n"));
         funcName2FuncInfo.put("upc_memget", fps("upc_memget", "", desc, "void", "void * restrict dst, shared const void * restrict src, size_t n"));
         funcName2FuncInfo.put("upc_memset", fps("upc_memset", "", desc, "void", "shared void *dst, int c, size_t n"));
         funcName2FuncInfo.put("upc_phaseof", fps("upc_memset", "", desc, "size_t", "shared void *ptr"));
         funcName2FuncInfo.put("upc_resetphase", fps("upc_resetphase", "", desc, "void", "shared void *ptr"));
         funcName2FuncInfo.put("upc_threadof", fps("upc_threadof", "", desc, "size_t", "shared void *ptr"));
         funcName2FuncInfo.put("upc_unlock", fps("upc_unlock", "", desc, "void", "upc_lock_t *ptr"));
         funcName2FuncInfo.put("shared", fps("shared", "", desc, "", ""));

         // set title
         setTitle(TITLE);
 	}

 	/**
 	 * Convenience function for inputting these FunctionPrototypeSummary and FunctionSummary arguments.
 	 * @param name
 	 * @param namespace
 	 * @param description if empty will do lookup in Map
 	 * @param returnType
 	 * @param args
 	 * @return
 	 */
 	protected IFunctionSummary fps(String name, String namespace, String description, String returnType, String args){
 		if(description==null || description.length()==0) {
 			description=getDesc(name);
 		}
 		IFunctionSummary fps = new FunctionSummaryImpl(name, namespace, description,
                 new FunctionPrototypeSummaryImpl(name, returnType, args), null);
 		return fps;
 	}
 	protected String getDesc(String key) {
 		String description = (String)desc.get(key);
 		if(description==null)
 			description=key+" description";
 		return description;
 	}

 	/**
 	 * Workaround for https://bugs.eclipse.org/bugs/show_bug.cgi?id=237331
 	 * ("CHelpProvider not called for UPC")
 	 * so that UPC help will get called.
 	 * CDT bug fix required for this to work otherwise.
 	 * For example, in TranslationUnit to make the UPC type 'inherit' from the C type.
 	 * <p>
 	 * This returns an invalid number as a workaround.
 	 * This will cause the default part of the switch in CHelpBookDescriptor.matches()
 	 * to execute and the UPC help will
 	 * match for all files. Not pretty but it will work for now.
 	 * @see org.eclipse.cdt.internal.core.model.TranslationUnit
 	 *
 	 */
 	@SuppressWarnings("restriction")// just for the javadoc comment to not get warning :)
 	@Override
 	public int getCHelpType() {
 		return -1;
 	}
 }
	/**********************************************************************
	* Copyright (c) 2008 IBM Corporation.
	* All rights reserved. This program and the accompanying materials
	* are made available under the terms of the Eclipse Public License v1.0
	* which accompanies this distribution, and is available at
	* http://www.eclipse.org/legal/epl-v10.html
	*
	* Contributors:
	* IBM Corporation - initial API and implementation
	*******************************************************************************/
	package org.eclipse.ptp.pldt.upc.editorHelp;

	import java.util.HashMap;
	import java.util.Map;

	import org.eclipse.cdt.ui.IFunctionSummary;
	import org.eclipse.ptp.pldt.common.editorHelp.CHelpBookImpl;
	import org.eclipse.ptp.pldt.common.editorHelp.FunctionPrototypeSummaryImpl;
	import org.eclipse.ptp.pldt.common.editorHelp.FunctionSummaryImpl;
	import org.eclipse.ptp.pldt.upc.UPCPlugin;

	/**
	* UPC help book - this is the information that is used for the hover help
	* <p>
	* <b>Note:</b> This (and F1/dynamic help as well) requires a fix to CDT post-5.0.0 release
	* to org.eclipse.cdt.internal.core.model.TranslationUnit - to recognize content-type of UPC to be a deriviative ("kindOf") the C content type.
	* <p>See https://bugs.eclipse.org/bugs/show_bug.cgi?id=237331
	* @author Beth Tibbitts
	*
	*/
	public class UPCCHelpBook extends CHelpBookImpl {
	private static final String TITLE = "UPC C Help Book";
	private Map<String,String> desc=new HashMap<String, String>();


	public UPCCHelpBook() {
	super(UPCPlugin.getPluginId());
	// populate description map - this just makes the funcName2FuncInfo init lines a bit more terse

	desc.put("upc_addrfield", "Returns an implementation-defined value reflecting the <q>local address</q>of the object pointed to by the pointer-to-shared argument.");
	desc.put("upc_affinitysize", "A convenience function which calculates the exact size of the local portion of the data in a shared object with affinity to <code>threadid</code>.");
	desc.put("upc_all_alloc", "Allocates shared space");
	desc.put("upc_all_broadcast", "Copies a block of memory with affinity to a single thread to a block of shared memory on each thread.");
	desc.put("upc_all_lock_alloc", "Dynamically allocates a lock and returns a pointer to it. The lock is created in an unlocked state.");
	desc.put("upc_all_exchange", "Copies the ith block of memory from a shared memory area that has affinity to thread j to the jth block of a shared memory area that has affinity to thread i");
	desc.put("upc_all_gather", "Copies a block of shared memory that has affinity to the ith thread to the ith block of a shared memory area that has affinity to a single thread.");
	desc.put("upc_all_gather_all", "Copies a block of memory from one shared memory area with affinity to the ith thread to the ith block of a shared memory area on each thread.");
	desc.put("upc_all_lock_alloc", "Dynamically allocates a lock and returns a pointer to it. The lock is created in an unlocked state.");
	desc.put("upc_all_permute", "Copies a block of memory from a shared memory area that has affinity to the ith thread to a block of a shared memory that has affinity to thread perm[i].");
	desc.put("upc_all_scatter", "Copies the ith block of an area of shared memory with affinity to a single thread to a block of shared memory with affinity to the ith thread.");
	desc.put("upc_alloc", "Allocates shared space of at least nbytes with affinity to the calling thread.");
	desc.put("upc_free", "Frees dynamically allocated shared storage");
	desc.put("upc_global_alloc","Allocates shared space");
	desc.put("upc_global_exit","Flushes all I/O, releases all storage, and terminates the execution for all active threads.");
	desc.put("upc_global_lock_alloc", "Dynamically allocates a lock and returns a pointer to it. The lock is created in an unlocked state.");
	desc.put("upc_local_alloc","Deprecated. Use upc_alloc instead.\nAllocates shared space.");
	desc.put("upc_lock_attempt", "Attempts to set the state of a lock to locked. Return code indicates previous state.");
	desc.put("upc_lock_free", "Frees all resources associated with a lock.");
	desc.put("upc_lock_t", "UPC type for a lock");
	desc.put("upc_lock", "Sets the state of a lock to locked.");
	desc.put("upc_memcpy", "Copies n characters from a shared object having affinity with one thread to a shared object having affinity with the same or another thread.");
	desc.put("upc_memget", "Copies n characters from a shared object with affinity to any single thread to an object on the calling thread.");
	desc.put("upc_memset", "Copies a value, converted to an unsigned char, to a shared object with affinity to any single thread.");
	desc.put("upc_phaseof", "Returns the phase component of the pointer-to-shared argument.");
	desc.put("upc_resetphase", "Returns a pointer-to-shared which is identical to its input except that it has zero phase");
	desc.put("upc_threadof", "Returns the index of the thread that has affinity to the shared object pointed to by the argument.");
	desc.put("upc_unlock", "Sets the state of a lock to unlocked.");
	desc.put("shared", "this is a shared UPC keyword");


	// populate func map
	//funcName2FuncInfo.put("upc_free", new FunctionSummaryImpl("upc_free", "", "upc_free test description",
	// new FunctionPrototypeSummaryImpl("upc_free", "void", "shared void *ptr"), null));
	String desc = ""; // will do map lookup for description in fps method.
	funcName2FuncInfo.put("upc_addrfield", fps("upc_addrfield", "", desc, "size_t", "shared void *ptr"));
	funcName2FuncInfo.put("upc_affinitysize", fps("upc_affinitysize", "", desc, "size_t", "size_t totalsize, size_t nbytes, size_t threadid"));
	funcName2FuncInfo.put("upc_all_alloc", fps("upc_all_alloc", "", desc, "void", "size_t nblocks, size_t nbytes"));
	funcName2FuncInfo.put("upc_all_broadcast", fps("upc_all_broadcast", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
	funcName2FuncInfo.put("upc_all_exchange", fps("upc_all_exchange", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
	funcName2FuncInfo.put("upc_all_gather_all", fps("upc_all_gather_all", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
	funcName2FuncInfo.put("upc_all_gather", fps("upc_all_gather", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
	funcName2FuncInfo.put("upc_all_lock_alloc", fps("upc_all_lock_alloc", "", desc, "upc_lock_t", "void"));
	funcName2FuncInfo.put("upc_all_permute", fps("upc_all_permute", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, shared const int * restrict perm, size_t nbytes, upc_flag_t flags"));
	funcName2FuncInfo.put("upc_all_scatter", fps("upc_all_scatter", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t nbytes, upc_flag_t flags"));
	funcName2FuncInfo.put("upc_alloc", fps("upc_alloc", "", desc, "void", "size_t nbytes"));
	funcName2FuncInfo.put("upc_free", fps("upc_free", "", desc, "void", "shared void *ptr"));
	funcName2FuncInfo.put("upc_global_alloc", fps("upc_global_alloc", "", desc, "void", "int status"));
	funcName2FuncInfo.put("upc_global_exit", fps("upc_global_exit", "", desc, "void", "int status"));
	funcName2FuncInfo.put("upc_global_lock_alloc", fps("upc_global_lock_alloc", "", desc, "upc_lock_t", "void"));
	funcName2FuncInfo.put("upc_local_alloc", fps("upc_local_alloc", "", desc, "void", "size_t nblocks, size_t nbytes"));
	funcName2FuncInfo.put("upc_lock_attempt", fps("upc_lock_attempt", "", desc, "int", "upc_lock_t *ptr"));
	funcName2FuncInfo.put("upc_lock_free", fps("upc_lock_free", "", desc, "upc_lock_t", "void"));
	funcName2FuncInfo.put("upc_lock", fps("upc_lock", "", desc, "void", "upc_lock_t *ptr"));
	funcName2FuncInfo.put("upc_memcpy", fps("upc_memcpy", "", desc, "void", "shared void * restrict dst, shared const void * restrict src, size_t n"));
	funcName2FuncInfo.put("upc_memget", fps("upc_memget", "", desc, "void", "void * restrict dst, shared const void * restrict src, size_t n"));
	funcName2FuncInfo.put("upc_memset", fps("upc_memset", "", desc, "void", "shared void *dst, int c, size_t n"));
	funcName2FuncInfo.put("upc_phaseof", fps("upc_memset", "", desc, "size_t", "shared void *ptr"));
	funcName2FuncInfo.put("upc_resetphase", fps("upc_resetphase", "", desc, "void", "shared void *ptr"));
	funcName2FuncInfo.put("upc_threadof", fps("upc_threadof", "", desc, "size_t", "shared void *ptr"));
	funcName2FuncInfo.put("upc_unlock", fps("upc_unlock", "", desc, "void", "upc_lock_t *ptr"));
	funcName2FuncInfo.put("shared", fps("shared", "", desc, "", ""));

	// set title
	setTitle(TITLE);
	}

	/**
	* Convenience function for inputting these FunctionPrototypeSummary and FunctionSummary arguments.
	* @param name
	* @param namespace
	* @param description if empty will do lookup in Map
	* @param returnType
	* @param args
	* @return
	*/
	protected IFunctionSummary fps(String name, String namespace, String description, String returnType, String args){
	if(description==null \|\| description.length()==0) {
	description=getDesc(name);
	}
	IFunctionSummary fps = new FunctionSummaryImpl(name, namespace, description,
	new FunctionPrototypeSummaryImpl(name, returnType, args), null);
	return fps;
	}
	protected String getDesc(String key) {
	String description = (String)desc.get(key);
	if(description==null)
	description=key+" description";
	return description;
	}

	/**
	* Workaround for https://bugs.eclipse.org/bugs/show_bug.cgi?id=237331
	* ("CHelpProvider not called for UPC")
	* so that UPC help will get called.
	* CDT bug fix required for this to work otherwise.
	* For example, in TranslationUnit to make the UPC type 'inherit' from the C type.
	* <p>
	* This returns an invalid number as a workaround.
	* This will cause the default part of the switch in CHelpBookDescriptor.matches()
	* to execute and the UPC help will
	* match for all files. Not pretty but it will work for now.
	* @see org.eclipse.cdt.internal.core.model.TranslationUnit
	*
	*/
	@SuppressWarnings("restriction")// just for the javadoc comment to not get warning :)
	@Override
	public int getCHelpType() {
	return -1;
	}
	}